view release on metacpan or  search on metacpan

OODoc/Styles.pod  view on Meta::CPAN

=head1	NAME

OpenOffice::OODoc::Styles - Document styles and layout processing

=head1	DESCRIPTION

This class is designed to handle styles, whether automatic or named,
contained in styles.xml or content.xml. It inherits from the common
OpenOffice::OODoc::XPath class and brings style-focused features.

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

Remember that named styles are those that the end user can see and
edit using through the GUI of an interactive office software (for ex. the
Stylist tool in OpenOffice.org).

Such styles usually have meaningful names and are stored in the styles.xml
member. But an OpenDocument-compliant style may own two names, so-called
'name' and 'display-name'. The 'display-name' is the name as it's displayed
by the office software, while the 'name' is the main identifier. Both are
displayable character strings, but they often differ. For a given
'display-name', the application software is allowed to set any arbitrary
'name'. For example, with OpenOffice.org 2, the well-known pre-defined
style whose display name is "Text body" is named "Text_20_body" (the space
character is replaced by its hexadecimal value between two "_" characters).
In the other hand, the 'name' and the 'display-name' generally don't differ
when they contain letters and/or digits only. Remember that the 'name' (and
not the 'display-name') is the main identifier of a style element. So, such
a method as getStyleElement("style name") uses the 'name' attribute to
retrieve a style descriptor and, in case of failure, it attempts to retrieve
the same element by 'display-name' (unless you change this behaviour through the
'retrieve_by' document property).

Care should be taken particularly with predefined base styles in
OpenOffice.org. These styles are described in styles.xml just like
named styles, but they appear to the end user with localised names
(in their local language), so the really displayed style name is neither
the 'name' nor the 'display-name' stored attributes. For example, in the
French distribution of OpenOffice.org, the "Text body" style appears as
"Corps de texte", while its "display-name" is "Text body" and its "name"
is "Text_20_body". This localization is hard-coded in the office software
for a few predefined styles, and it's not stored in the file. However, this
is not a problem for user-defined styles as the stored display-name is exactly
the same as the effective display name.

There are also numerous "automatic" styles in a document which are
created implicitly by the office application each time a particular
set of presentation attributes is given to an element, but where no
named style is referenced. Automatic styles which apply to the
document body are stored in content.xml (but in an XML element
isolated from the content). An automatic style's name can change
randomly each time the document is edited or saved through an interactive
desktop application. Applications which access automatic styles will not
want to indicate them using "hard-coded" names. The best way is to
retrieve each automatic style via an object that is known to use it.
Using a "hard-coded" name is all right for styles created by a
program (the createStyle() method requires it), but such a name should
only be considered to be stable for the duration of the session. If
you want a program-created style name to be then respected by
OpenOffice.org, you must create it as a named style. This is no more
complicated, but it is better to avoid making hundreds of styles
visible to the user that they do not need to see.

There are some structural differences between the old OpenOffice.org 1.0
format and the OASIS OpenDocument (ODF) one. A few of these differences
aren't made fully transparent by OpenOffice::OODoc. So, in some cases, a
program including style definitions or updates doesn't produce exactly the
same results with both OOo 1 and ODF documents.

The page styles are more complex than the other usual styles. A page style
Some styles are more complex than others as they describe the page layout.
so called "master page", can actually define a header, a footer, margins,
and a background.

Page headers and footers can contain text and images; as a consequence,
some of their features can be handled by OODoc::Text and OODoc::Image.

A background contains a colour and can also include a background image (several
methods are possible).

Presentation of these objects is itself controlled by styles.

All of this leads to the conclusion that it is not enough just to
associate each content element with a style. In reality, document
styles form a rather complex network of interdependencies.

As for page styles, the OpenDocument format contains a concept
which must be understood in order to use some of the following
methods. By virtue of the principle of separation of content and
presentation, the definition of a page style is based on two
distinct objects: "master page" and "page layout". A "master page"
object encompasses any page style content (i.e. the content of
headers and footers) and links to a "page layout" object which
describes page presentation characteristics (with large numbers of
parameters from page dimensions to background colour to footnote
separator size, etc.). Names which appear in the list of page styles
in OpenOffice.org are actually names of "master pages". However, to
work with physical aspects of the presentation, you have to access
the associated "page layout".

To complicate matters, there are also header and footer styles. Each
object contained in a header or footer (e.g. paragraph or image) has
a style. The number and range of styles are much larger that you
would imagine just looking at the style management tool in any office
software. Up to a point, OODoc::Styles methods make life easier for you by
masking some of this complexity.

In OODoc::Styles methods, styles are normally indicated by their
logical names (which must be unique), but, except where otherwise
stated, they can also be indicated by their style element reference as well.
Moreover, when a method is expecting a page layout as an argument
but the programmer passes it a master page instead (whether by
design or by mistake), it "knows" in most cases how to automatically