=head1 NAME
OpenOffice::OODoc::Text - The text processing submodule of OpenOffice::OODoc
=head1 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 OpenOffice.org Writer 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. It describes 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 OpenOffice.org 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.
=head2 Methods
=head3 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.
=head3 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.
=head3 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.
=head3 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 (2006/03).
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 by reference 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.
An 'attachment' option is allowed (see eppendParagraph() for details
about this option).
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.
=head3 appendItem(list [, text => text ,style => style ,[other_options]])
See appendListItem().
=head3 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.
=head3 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.
=head3 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 section or 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().
=head3 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.
=head3 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 through OpenOffice.org; "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()
=head3 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'
);
=head3 appendTableRow(table)
See appendRow.
=head3 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. So we recommend
you to have a look at the Open Office XML specification and/or the
OOo bibliographic project (http://bibliographic.openoffice.org) in
order to know the generally accepted properties.
=head3 bookmarkElement(element, name [, offset])
See setBookmark().
=head3 cellCurrency(table, row, column [, currency])
=head3 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'.
=head3 cellFormula(table, row, column [, formula])
=head3 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 OpenOffice.org.
Note 2: syntax and functionality of cell formulae differ greatly
between the Writer and Calc applications.
=head3 cellSpan(table, row, column [, span])
=head3 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.
This method works only for horizontal expansion.
The text of the covered cells (if any) is concatenated to the original
content of the expanded cell (as in OOo Writer or Calc).
Caution: when related to table cells, "span" has not the same
meaning as when related to flat text (see getSpan() and setSpan()).
=head3 cellStyle(table, row, column [, stylename])
=head3 cellStyle(cell [, stylename])
Get or set the style of a table cell.
=head3 cellValue(table, row, column [, value [, text]])
=head3 cellValue(cell [, value [, text]])
Without the "value" argument: see getCellValue().
With "value" (and, optionally, "text"): see updateCell().
=head3 cellValueType(table, row, column [, type])
=head3 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);
=head3 columnStyle(column_element [, style])
=head3 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.
=head3 copyRowToHeader(table, rownum)
=head3 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 createTextBoxElement(options)
Creates a new text box according to the given options.
Knowing that a text box is a particular frame, see createFrame() in
the OpenOffice::OODoc::XPath manual page for generic options (some
of them are mandatory if you need to create a really visible box).
An additional 'content' option is allowed for a text box:
'content' => string or text container
The 'content' option is either the litteral content of the text, or
the reference of an existing text container (such as a paragraph).
Example:
my $para = $doc1->getParagraph(4);
my $slide = $doc2->getDrawPage("Slide4");
$doc2->createTextBox
(
attachment => $slide,
size => '10cm, 2cm',
position => '2cm, 3cm',
content => $para->copy;
);
This example inserts a text box in a presentation document ($doc2)
and fills it with a copy of a paragraph extracted from a text
document ($doc1).
Note that this method works on text documents as well as presentation
or drawing documents.
=head3 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.
=head3 deleteBookmark(name)
Deletes the given bookmark (if defined).
Works with position bookmarks only.
=head3 deleteColumn(table, col_num)
=head3 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.
=head3 deleteRow(table, row_num)
=head3 deleteRow(row_elt)
Deletes a given row in a table.
=head3 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.
=head3 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");
=head3 deleteTableColumn(table, col_num)
See deleteColumn().
=head3 deleteTableRow(table, row_num)
See deleteRow().
=head3 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.
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" => rgb2oo("blue"),
"fo:background-color" => rgb2oo("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.
=head3 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 regex).
Example:
my @biblio = $doc->getBibliographyElements("^W3C");
returns the bibliographic entries where the identifier begins with
"W3C".
=head3 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.
=head3 getCell(table, row, column)
=head3 getCell(table, coord)
=head3 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.
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.
=head3 getCellParagraph(table, row, column)
=head3 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.
=head3 getCellParagraphs(table, row, column)
=head3 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).
=head3 getCellValue(table, row, column)
=head3 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.
=head3 getChapter(header_no [, options])
This method returns the list of the elements depending (from the
end-user's point of view) on a given heading element. The argument
and the options are the same as with getHeading().
Example:
my @list = $doc->getChapter(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.
Caution, this method returns a list of elements and not an element.
Chapters, unlike sections, are not defined in OpenDocument. So,
getChapter() should be used as a possible workaround in order to
isolate a logical set of content elements which is not packaged in
a section.
=head3 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.
=head3 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.
=head3 getEndnoteCitationList()
Returns the list of all the endnote citations (i.e. references to
footnotes included in the text) contained in the document.
=head3 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".
=head3 getFootnoteCitationList()
Returns the list of all the footnote citations (i.e. references to
footnotes included in the text) contained in the document.
=head3 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".
=head3 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 getChapter().
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.
=head3 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.
=head3 getHeaderRow(table [, row_number])
See getTableHeaderRow().
=head3 getHeadingText(n)
Returns the text of the nth+1 heading element. Elements are counted
in the same way as for getHeading().
=head3 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').
=head3 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.
=head3 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.
=head3 getLevel(element)
See getOutlineLevel().
=head3 getList(n)
See getItemList().
=head3 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.
=head3 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").
=head3 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.
=head3 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()).
=head3 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.
=head3 getNoteElementList()
Returns the list of the endnote and footnote main elements.
=head3 getNoteList()
Returns the list of the endnote and footnote body elements.
=head3 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.
=head3 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";
}
=head3 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.
=head3 getParagraphList()
Returns a list of paragraph elements (i.e. 'text:p' elements in the
document body).
=head3 getParagraphText(n)
Returns the text of the nth+1 paragraph, counted using the same
rules as for getParagraph.
=head3 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").
=head3 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().
=head3 getRowCells(table, row)
=head3 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.
=head3 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.
=head3 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.
=head3 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.
=head3 getStyle(path, position)
=head3 getStyle(element)
Obsolete. See textStyle.
=head3 getTable(number [, length, width])
=head3 getTable(name [, length, width])
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 OpenOffice.org Writer documents, but not allowed
in OpenOffice.org spreadsheets).
The returned object is a "handle" that can be used for subsequent
accesses to its components (rows, cells).
getTable() can be used to retrieve a sheet in a Calc document as
well as a table in a Writer document. However, before using any of
the row/column/cell manipulation available methods, a special
preprocessing should be done if the target table is a spreadsheet.
See normalizeSheet() for more information.
A getTable() call with the optional length, width arguments produces
the same effect as an explicit call of normalizeSheet() with the same
arguments.
In the text documents, the tables may be used without preprocessing
and the paragraph above doesn't apply, as long as the application
doesn't to get other objects than rows and cells. However, the table
normalization is needed before any column-oriented operation (i.e.
getColumn(), insertColumn() or deleteColumn()).
The returned value is a table element and not a table's content.
=head3 getTableColumn(table, column)
See getColumn.
=head3 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()).
=head3 getTableList()
Returns a list of table elements in a document.
=head3 getTableRow(table, row)
See getRow.
=head3 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.
=head3 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 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.
=head3 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.)
=head3 getText(path, position)
=head3 getText(element)
Exports the text contained in the given element according to the
means appropriate to that type of element. Works on a large set
of text containers in any document class.
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-OpenOffice.org 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().
If the element is a text box, getText() extracts its text content.
=head3 getTextBox(n)
=head3 getTextBoxElement(n)
Retrieves a text box by order number or by name.
If the argument contains digits only, it's regarded as a text box
number (relative to the current context, which is the whole document
by default).
If the argument contains one or more non-digit characters, the method
behaves like selectTextBoxElementByName().
=head3 getTextBoxElements()
Returns the list of the existing text boxes.
=head3 getTextBoxes()
See getTextBoxElements().
=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('.*').
=head3 getTextElementList()
Returns the list of all the text elements, including headers,
paragraphs and item lists.
=head3 getTopParagraph(n)
Same as getParagraph but only considers top level paragraphs. The
contents of lists, tables and footnotes are excluded.
=head3 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.
=head3 getUserFieldElement(name)
Returns the element (if defined) representing a user-defined field,
and corresponding to the given name. See also userFieldValue().
=head3 getVariableElement(name)
Returns the user-defined variable identified by the given name.
[Contribution by Andrew Layton]
=head3 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.
=head3 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).
=head3 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).
=head3 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.
=head3 insertHeading(path, position, options)
=head3 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.
=head3 insertItemList(path, position [, options])
=head3 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.
=head3 insertParagraph(path, position [, options])
=head3 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.
=head3 insertRow(table, row [, options])
=head3 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.
=head3 insertSection(path, position, name [, options])
=head3 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.
=head3 insertString(path, position, text, offset)
=head3 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).
=head3 insertTable(path, position, name, rows, columns [, options])
=head3 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.
=head3 insertTableColumn(table, col_num [, options])
See insertColumn().
=head3 insertTableRow(table, row [, options])
=head3 insertTableRow(row_element [, options])
See insertRow().
=head3 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.
=head3 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 (sxw/odt) 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.
=head3 normalizeTable(table [, rows [, columns]])
See normalizeSheet().
=head3 outputDelimitersOn()
=head3 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.
=head3 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).
=head3 removeBookmark(id)
See deleteBookmark().
=head3 removeHeading(position)
=head3 removeHeading(element)
Removes the heading at the given position (first form).
Example:
$doc->removeHeading(4);
removes the 5th heading (whatever its level) counted from the
beginning of the document.
The heading 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().
=head3 removeHyperlink(path, position)
=head3 removeHyperlink(element)
Removes any hyperlink contained in the given element, leaving
in place the previously hyperlinked text.
=head3 removeParagraph(position)
=head3 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.
=head3 removeCellSpan($cell)
Removes the multi-column span of a table cell. The width of the cell
is reduced to the width of its column. The uncovered cells take the
same style and data type as the reduced cell.
=head3 removeSpan(path, position)
=head3 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().
=head3 renameSection(section, newname)
Renames an existing section using the second argument.
=head3 renameTable(table, newname)
Renames an existing table using the second argument.
=head3 rowStyle(row_element [, style])
=head3 rowStyle(table, row [, style])
Reads or modifies a table row's style, in the same way as
columnStyle does for columns.
=head3 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().
=head3 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.
=head3 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.
=head3 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).
=head3 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().
=head3 selectElementsByContent(filter)
=head3 selectElementsByContent(filter, replacement)
=head3 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
paragraphs (as long as the paragraphs are directly attached to
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.
=head3 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.
=head3 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 regex.
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;
=head3 selectHyperlinkElements(url_filter)
Returns the list of the hyperlink elements whose the URL matches
the argument (and not only the first one).
=head3 selectParagraphByStyle(stylename)
Returns the first paragraph (if any) using the given style.
=head3 selectParagraphsByStyle(stylename)
Returns the list of the paragraphs using the given style.
=head3 selectTextBoxElementByName(name)
Returns the text box identified by the given name, if any.
Note: Unnamed text boxes can't be retrieved using this method.
See also getTextBoxElement().
=head3 selectTextContent(filter)
=head3 selectTextContent(filter, replacement)
=head3 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('.*');
=head3 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.
=head3 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").
=head3 setHyperlink(path, position, [context,] expression, url)
=head3 setHyperlink(element, [context,] expression, url)
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 presented according
a particular style. So, the last argument must be an URL instead
of a style.
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...).
=head3 setSpan(path, position, [context,] expression, style)
=head3 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 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).
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' represents the span filter; every substring contained
in the target element and matching it becomes a 'span'. This filter
is processed, up to some extent, as a regex, but there is no full
perl regex support here; for example, the regex parentheses are not
supported.
'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.
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).
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.
See also removeSpan.
=head3 setStyle(path, position, style_name)
=head3 setStyle(element, style_name)
Obsolete. See textStyle.
=head3 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 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.
=head3 textBoxContent(text_box [, new_content])
Returns the content of a given text box. If a second argument is
provided, it's used as the new content.
See the 'content' option of createTextBoxElement() for the possible
values of the content argument.
=head3 textBoxCoordinates(text_box [, coordinates])
Gets the current coordinates of a text box, or changes them if a
second argument is provided.
See getObjectCoordinates(), setObjectCoordinates() and
createFrameElement() in OpenOffice::OODoc::XPath for explanations
about coordinates syntax.
=head3 textBoxDescription(text_box [, new_description])
Gets the current description of a text box (if this description
exists, knowing that it's optional). If a second argument is
provided, it's used as the new description.
=head3 textBoxSize(text_box [, new_size])
Gets the current size of a text box, or changes it if a second
argument is provided.
See getObjectSize(), setObjectSize() and createFrameElement() in
OpenOffice::OODoc::XPath for explanations about size syntax.
=head3 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.
=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.
=head3 textStyle(path, position [, style])
=head3 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.
=head3 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".
=head3 unlockSections()
Removes the write protection of every section in the document.
=head3 updateCell(table, row, column, value [, text])
=head3 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.
=head3 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.
=head3 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]
=head2 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.
=head3 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)
=head3 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.
=head2 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.
=head1 AUTHOR/COPYRIGHT
Copyright 2004-2006 by Genicorp, S.A. (http://www.genicorp.com)
Initial developer: Jean-Marie Gouarne (http://jean.marie.gouarne.online.fr)
Initial English version of the reference manual
by Graeme A. Hunter (graeme.hunter@zen.co.uk)
License:
- Genicorp General Public Licence v1.0
- GNU Lesser General Public License v2.1
Contact: jmgdoc@cpan.org
=cut