=head1	NAME

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


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 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 (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". However, this is not a problem for user-defined styles
as the stored display-name is exactly the same as the effective display

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 in
OpenOffice.org. 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 new OASIS Open Document (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 OOo 2

Some styles are more complex than others as they describe the page
layout. These styles can themselves contain text and images. A page
style, or a "master page", can actually define a header, a footer, margins,
and a background.

Headers and footers can contain text and images which can otherwise
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 OpenOffice.org 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 Stylist tool in OpenOffice.org. 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.
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
select the associated page layout.

Defining a style requires a great many attributes. Some appear in
code examples in this manual, but for a full list of possible
attributes for each style, you must refer to the OpenOffice.org
specification or publications derived from it.

OODoc::Styles module is designed to allow applications to manipulate
any style and even create new ones. It is not recommended, however,
to use it to create a presentation entirely from code. Here again,
it is better to start from document templates which already contain
at least a blank of each required style.

=head2	Methods

=head3	Constructor : OpenOffice::OODoc::Styles->new(<parameters>)

        Short form: ooStyles(<parameters>)

        See OpenOffice::OODoc::XPath->new.

        Returns an OODoc::XPath OpenDocument connector with additional
	style-aware features.
	The member loaded by default is "styles.xml" which gives access to
        named or automatic styles associated with the page layout. The
        "content.xml" member should be forced if the application is to work
        with styles associated with the document body (automatic styles

=head3	backgroundImageLink(page [, link])

        Allows you to check the background image's link (if found) for the
        page style given as the first argument. If another link is given as
        the second argument, it replaces the existing link.

        See imageLink in OODoc::Image about links. Put more simply, a link
        is the address of the graphics file which corresponds to the
        physical content of the image. Even though the background image
        belongs to the "page layout", the first argument can also be either
        a "master page" or a "page layout".

        If the second argument "link" is given, its value replaces the
        existing link in the same way as with imageLink.


            	("Standard", "http://www.genicorp.com/back.jpg");

        If the page did not have a background image before the call, one is
        created. It must, however, be an external linked image (as in the
        above example), unless the link represents the internal address of
        an already loaded image. This method does not itself carry out any
        physical import of an image.

        See also importBackgroundImage.

=head3	createMasterPage(name, options)

        Creates a new page style. Options are:

            'layout'	=> page layout name
            'next'	=> next master page style name

        The association with a "page layout" allows you to associate a
        layout to the page. Otherwise the page will have a default layout.


            		layout	=> 'pm1',
            		next	=> 'Standard'

        See the OpenDocument specification (or the 'Organizer' tab in the
        "Format/Page" dialog box of OpenOffice.org) if you want to know what
	a "Next Style" is. The optional "next" parameter simply gives the name
	of a "master page", which can be the one you are currently creating.

=head3	createPageLayout(name, options)

        Creates a new layout style (page layout) which can be used by a page
        style (master page). Options are the same as for updatePageLayout.

=head3	createPageMaster(name, options)

	See createPageLayout()

=head3	createStyle(name, options)

        Creates a new style of any type or class (depending on options) and
        returns its reference if successful.

        The first argument indicates the new style name which must be unique
        in the document. By default, a check is automatically done; the method
	fails and produces a warning if the style already exists. However,
	no check is done if a 'check' option is provided and set to 'false'.
	Avoiding the uniqueness check can improve the 
	If the external name of the style, as it could be made visible for the
	end-user through an OpenDocument-compliant editing software (such as
	OpenOffice.org), is not the same as the internal name, it may be set
	through a 'display-name' option. Without this option, the display name
	is the same as the internal name.

        If the active OODoc::Styles object is associated with a document
        content (content.xml), the new style is always taken to be an
        automatic style. If associated with the styles.xml member, the new
        style is considered to be a named style by default. However, the
        category => 'automatic' option (or category => 'auto') allows you to
        specify it as an automatic style. Please note: in the case of
        content.xml, the "category" option is ignored as all styles are
        automatic in this member.

        By default, the method stores a style in the form of an XML element
        "style:style" (which corresponds to the most commonly used content
        styles). Some style elements are indicated in a different way. The
        "namespace" and "type" options are available for this. If, for
        example, you want to create a footer configuration style (called
        "text:footnote-configuration" in the OpenOffice.org specification),
        you will have to specify the "footnote-configuration" type
        explicitly in the "text" namespace using one of the following two

            namespace		=> 'text',
            type		=> 'footnote-configuration'

        The other possible options are:

            namespace		=> namespace
            type		=> style type
            family		=> style family (text, paragraph, ...)
            class		=> style class
            parent		=> parent style (inherit)
            next		=> next style

        If other style "organisation" attributes (often for links to other
        styles) prove to be needed but are not on the above list, they must
        be grouped together in a hash provided by the application and
        indicated by a "references" option.

        Of course, if you create a new style, you do not just sort it into
        type, class or family, etc. You attribute its own presentation
        attributes which can be inherited by other styles which cite it as
        "parent". These personal attributes (whose nature obviously depends
        on the style type) are all attributed by the "properties" attribute
        which itself indicates a hash provided by the application.

        Here is an example of a paragraph style creation in an OOo 1

            	family	=> 'paragraph',
            	parent	=> 'Standard',
            	properties =>
			'fo:margin-left'	=> '2cm',
			'fo:margin-right'	=> '1.5cm',
			'fo:text-align'		=> 'justify',
            		'style:font-name'	=> 'Times',
            		'fo:font-size'		=> '14pt',
            		'fo:font-weight'	=> 'bold',
            		'fo:font-style'		=> 'italic',
            		'fo:color'		=> '#000080',
            		'fo:background-color'	=> '#ffff00'
            $doc->setStyle($doc->getParagraph(3), "P3");

        This sequence gives paragraph 3 of the document a lovely Times font
        in dark blue size 14 bold italics on a yellow background. This is
        done using a style called "Colour" (reusable later for other
        paragraphs) based on the "Standard" style. You will note that the
        colour codes are in RGB hexadecimal preceded by a '#'.
	We could replace '#000080' with odfColor('navy blue') if we used the
	standard rgb.txt colour table from the Xorg distribution (see
	odfColor() below). A large part of these layout properties come from
	the FO (Form Object) language, that is a part of the OpenDocument
	XML vocabulary. You should look at the OpenDocument Format
	specification for an exhaustive presentation of the supported FO

	In this example, "namespace" and "type" are not specified because
	the default namespace and type are appropriate here. (Rest assured
	that this is often the case when working with text styles.)

	Be careful: the example above works with an OOo 1 document, put some
	of the given properties are ignored with an OOo 2 one. See below about
	the differences between the two formats.

        Another example:

            	family	=> 'graphics',
            	parent	=> 'Graphics',
            	properties =>
            		'style:vertical-pos'	=> 'from-top',
            		'style:horizontal-pos'	=> 'from-left',
            		'style:vertical-rel'	=> 'page',
            		'style:horizontal-rel'	=> 'page',
            		'draw:luminance'	=> '4%',
            		'draw:contrast'		=> '2%',
            		'draw:gamma'		=> '1.1',
            		'draw:transparency'	=> '5%',
            		'draw:red'		=> '-3%',
            		'draw:green'		=> '2%'

        The "Photo1" style defined above is of course an image style i.e. in
        the "graphics" family, based on the parent graphics style
        "Graphics". Any images to which this style will be applied will have
        coordinates which relate to the upper left edge of the page measured
        from top to bottom and left to right. They will be presented with an
        increase in luminosity of 4% and contrast of 2%, gamma correction of
        1.1 and 5% transparency. Moreover, 3% less red and 2% more green
        will freshen the image and highlight the vibrancy of the
        chlorophyll. There are yet more in the list of options, so don't
        throw out your holiday snaps!

	While all the properties of a given style are directly available
	through a single "properties" structure in OOo 1 documents, they are
	stored in separate, specialised structures in OOo 2 (ODF) documents.
	A property name can be used (with different effects) in more than one
	property area. For example, with an OOo 2 document, we should rewrite
	our "Colour" style definition using 2 separate instructions as shown

            	family	=> 'paragraph',
            	parent	=> 'Standard',
            	properties =>
			'-area'			=> 'paragraph',
			'fo:margin-left'	=> '2cm',
			'fo:margin-right'	=> '1.5cm',
			'fo:text-align'		=> 'justify',
            	 	'fo:background-color'	=> '#ffff00'
		properties  =>
			'-area'			=> 'text',
            	 	'style:font-name'	=> 'Times',
			'fo:font-size'		=> '14pt',
            	 	'fo:font-weight'	=> 'bold',
            	 	'fo:font-style'		=> 'italic',
			'fo:color'		=> '#000080',

	The first instruction creates the style with properties that apply
	to the "paragraph" area. The second one brings additional properties
	for the text content of the paragraph. A paragraph style includes
	"paragraph properties", such as the margins, the text alignment, the
	background color, and "text properties", such as any font-focused
	attribute. The '-area' option is not a style property; it's only a
	switch that indicates what is the target property area. Without this
	option, the default area name is the family name (so, for a paragraph
	style, the default area for updateStyle() is "paragraph properties").
	This sophistication sounds strange at first look, but it could prove
	very useful because, knowing that the OpenDocument format brings more
	features than the old OOo format, the same property name can be
	used in more than one area, with different effects. For example,
	we could put a 'fo:background-color' in the 'text' area AND another
	one in the 'paragraph' area; the 'text' background color should apply
	to the text-covered areas only, while the 'paragraph' background
	is a rectangular area, that is not always fully covered by text.
	The same result could be obtained (more efficiently) with
	styleProperties() instead of updateStyle (see styleProperties()).
	The '-area' switch is silently ignored when used with OOo 1 documents,
	and sometimes required for ODF, so you can safely use it if you want
	to write portable code. In addition, up to now, the unknown style
	attributes are simply ignored by the OpenOffice.org software, and
	they don't harm. However, if the document is later edited and saved
	through OpenOffice.org, every unknown attribute is removed. As a
	consequence, everybody can use proprietary (non-OpenDocument) style
	attributes for application-specific markup.

	So, while OpenOffice::OODoc supports both OOo 1 and ODF with the
	same API, the present version can't completely hide the differences
	between the two formats. However, the program's logic can hide these
	differences for the end-user, because it can know the format of
	the current document (see isOpenDocument in OpenOffice::OODoc::XPath).

        Defining a style can be made a lot easier by reusing an already
	existing style than by creating it programmatically. The simplest way
	is by inheritance using the "parent" option, but the link to "parent"
        creates a permanent dependency (any further changes in the parent will
	affect the children). OODoc::Styles offers another possibility: copy
        the properties of an existing style, without creating a link to a
        parent, using the "prototype" option. This option points to another
        style whose properties are then taken up and combined with the new
        properties. New properties prevail over old ones if the new
        properties replace existing attributes in the prototype style, just
        like when they are inherited.


            	prototype	=> "Colour",
            	properties	=>
            		'fo:font-size'	=> '16pt'

        This new style called "Bigger" is an exact copy of the previously
	defined "Colour" style, except for the font size.

	The given "parent" style is not necessarily defined yet and, if the
	current document member is "content", it can be the name of a style
	defined in the "styles" member. (See getAncestorStyle() and

        Generally speaking, explicit parameters passed by an application
        (e.g. font size) prevail over prototype's parameters.

        The prototype parameter can be a style name (as in the above
        example) or a style element. If it's an element, its origin doesn't
	matter (it can be a copy of a style element previously extracted from
	another document). If it's a name, the prototype style is retrieved
	either in the current document (default) or, if the 'source' option
	is provided, in another document.
	The value of the 'source' option is another OODoc::Styles (or
	OODoc::Document) object. If this option is provided, createStyle
	looks in the indicated document for the prototype style. If 'source'
	is provided without 'prototype', the prototype style is supposed to
	have the same name as the style to be created.
        If you want to create a style called "MyStyle", for example, in
        document $doc1 which imitates a style called "HisStyle" in document
        $doc2 (where both documents are OODoc::Styles or OODoc::Document
        objects), you can do the following:

            		prototype	=> "HisStyle",
			source		=> $doc2
	but if you write
			source		=> $doc2
	the local style "MyStyle" is built as a copy of the so-named style
	in the source document (it's a direct import).
	Whatever the origin of the prototype style, any property can be
	set or redefined in the new style.

        Not only can you import styles available in other documents, but
	you can also create automatic styles in a 'content' member which
	are derived from named styles found in the 'styles' member and

	WARNING: The "prototype" option can produce unexpected results if
	the two documents are not in the same format. As a consequence,
	using an OOo 1 style as the prototype of an OpenDocument one (and
	vice-versa) should be avoided.

        Always be careful of dependencies. There are often dependencies
        between styles (heritage or usage). An application must be wary of
        importing styles without modification which are directly or
        indirectly dependent on other styles which are not available in the
        target document. Text styles are fairly easy to control in this way,
        but table, page and graphic styles, for example, have more complex

	When a font name is set (generally through a 'style:font-name'
	text property) in a new style, take care of the availability of
	the corresponding font declaration in the document. A font is not
	rendered if it's not declared (see importFontDeclaration()).
        See the OpenDocument specification (chapter 14, "Styles") for a
	complete list of possible attributes for each type of style.
	However, creating sophisticated styles from scratch is *not*
	recommended; remember the most easy (and the less error-prone) way
	consists of creating template documents through the OpenOffice.org
	GUI (or any other ODF-compliant office software) and using them as
	style libraries.

=head3	exportBackgroundImage(page [, destination])

        Exports the graphics file which corresponds to the background image
        of a page style where the image exists and is internal to the
        OpenOffice.org archive. (A linked image is obviously not exportable
        since it is not actually present in the document.) See the
        exportImage method in OODoc::Image for export details.


            	("First Page", "C:\Images\backgrnd.jpg");

=head3	getAncestorStyle(style)

	Returns the name of the primary known ancestor of the given style.

	If the style has a standalone definition (i.e. it's its own ancestor),
	the method returns it's name.

	This method returns the ancestor name as it's known in the current
	document space. The genealogy is not followed out of the scope of
	the current XML member.
	For example, if we have an automatic paragraph style "P1", defined in
	the "content" member and derived from "Text body", the returned
	ancestor name will be "Text body". However, "Text body" itself could
	be a derivative of "Standard". But "Text body" is defined in the
	"styles" member, so its definition (including the name of its parent
	style) is out of the scope.

	As a consequence, in a regular OOo document, there are 2 possible

	- if the current space is "styles", the returned style name is really
	the name of the primary ancestor, because a style defined in this
	space can't inherit from anything elsewhere;

	- if the current space is "content", the returned value can be the
	name of a style defined elsewhere.

	A possible check is a simple call to getStyleElement() with the
	returned ancestor name. If getStyleElement() returns undef, then
	the ancestor style is not defined in the current space (and, if
	needed, we could reach it the "styles" member, if we currently work
	with the "content" member).

	See also getParentStyle().

=head3	getAutoStyleList([options])

        Returns a list of automatic style elements in the current document.
        By default, only "style" type elements in the "style" namespace are
        returned. You can select special styles using the "namespace" and
        "type" options.

        For example, if you want to get a list of number styles (namespace
        "number", type "number-style"), do it like this:

            my @styles = $doc->getAutoStyleList
            	(namespace => 'number', type => 'number-style');
=head3	getAutoStyleRoot()

	Returns the element that contains all the automatic style elements.
	See also getNamedStyleRoot().

=head3	getBackgroundImageAttributes(page)

        Returns the attributes of the given page style's background image
        (if any), in the form of a hash (attribute => value).

=head3	getBackgroundImageElement(page)

        Returns the element reference of the given page style's background
        image (if found).

=head3	getDefaultStyleAttributes(default_style)

        Returns the given default style's attributes (if any). Default
        styles are generally "paragraph" and "graphics". See also

=head3	getDefaultStyleElement(family)

        Returns the default style element's reference given by its logical

        A default style describes default values assigned to certain
        attributes of a given style family.

        For example, to get the default paragraph style of a document, use:

            my $def_para = $doc->getDefaultStyleElement("paragraph");

=head3	getFontDeclaration(fontname)

	Returns the font declaration element corresponding to the given font
	name, or undef if the font is not declared in the current document.
		unless ($doc->getFontDeclaration("Times New Roman"))
			$doc->importFontDeclaration($doc2, "Times New Roman");

	(See also importFontDeclaration.)

=head3	getFooterParagraph(masterpage, number)

        In a text document, returns a footer paragraph's reference, if the
	master page has a footer and the paragraph exists. Arguments are
	master page and paragraph number.
	Caution: the first argument can't be a page number, knowing that
	printable pages are dynamically created by the office software and
	don't exist in the stored document.

=head3	getHeaderParagraph(masterpage, number)

        Like getFooterParagraph, but for a header.

=head3	getMasterPageElement(page)

        Returns a master page element reference whose logical name is given,
        or undef if the page style is not found. You can also pass an
        element reference instead of a name. In this case, the method's role
        is simply to check if the element is indeed a master page type. If
        so, it returns the argument as is. If not, it returns undef.
	Look at the DESCRIPTION part of the present manual chapter for a few
	explanations about master pages (and, of course, feel free to dig in
	the OpenDocument specification for details).
	This method should preferently be used on the 'styles' member; it
	doesn't generally make sense with the 'content' member, knowing that
	the master pages are generally described as named styles.

=head3	getMasterStyleList([options])

	Returns a list of master styles in the current document. By default,
	the list contains the master page elements.
	Other kinds of styles may be retrieved, according to the 'namespace'
	and/or 'type' options (see getStyleElement()). But the search space
	is limited to the master styles area, whatever the type and the

	Like getMasterPageElement(), this method makes more sense on 'styles'
	members than on 'content' ones.
=head3	getMasterStyleRoot()

	Like getNamedStyleRoot(), but the returned element contains the
	master style descriptors instead.	

=head3	getNamedStyleList([options])

        Returns a list of named styles in the current document, using the
        same options as for getAutoStyleList. By definition, in
        OpenOffice.org documents this list should be empty in all elements
        except styles.xml.
=head3	getNamedStyleRoot()

	Returns the root element of the named styles area. In other words,
	this method retrieves the element that contains all the named style
	elements, with the exception of the master styles.
	This element could be, for example, copied from a document to another
	one in order to use exactly the same named styles (user-defined or
	provided with the office software) in both.

=head3	getOutlineStyleElement(level)

	Returns the outline style descriptor related to the given outline
	level. The returned element is available for subsequent get/set
	operations using getAttributes(), setAttributes(), and so on.
	See also updateOutlineStyle().
=head3	getPageLayoutAttributes(page)

        Returns the description of a page layout. The argument can be
        either a page layout directly or a master page style which
        refers to it.

        The structure of returned data is a hash of hashes. It contains four
        elements, each of which is a hash. As follows:

            - "references": style reference attributes with at least its
            name and possibly its links to other styles.
            - "properties": background description (dimensions, orientation,
            margins, colour, etc.).
            - "header": presentation attributes for the header.
            - "footer": presentation attributes for the footer.
            - "footnote-sep": footnote separator attributes.
            - "background-image": background image attributes.

        Attributes are displayed according to OpenOffice.org specifications.

=head3	getPageMasterAttributes(page)

	See getPageLayoutAttributes()

=head3	getPageLayoutElement(page)

        Returns the page layout element reference from a search argument
        which can be either a logical name or a page style reference. If the
        argument is a master page, the method returns the corresponding page

=head3	getPageMasterElement(page)

	See getPageLayoutElement()

=head3	getParentStyle(style)

	Returns the name of the parent of the given style, or undef if the
	style has a standalone definition (without inheritance).

	The returned parent name can be the name of a style defined elsewhere
	(or not defined yet).

	See also getAncestorStyle().

=head3	getStyleAttributes(style)

        Returns a style's description (other than a page style) given as a
        logical name or reference.

        The structure of returned data is a hash of hashes. It contains the
        two following elements:

            - "references": style reference attributes with at least its
            name and possibly its links to other styles (either its family,
            parent style, class and/or next style).
            - "properties": description of the presentation characteristics
            for this style (and which depend on the type of object the style
            is applied to).

        Remember that this structure can be used directly by an application
        to create or update another style.

=head3	getStyleElement(style [, options])

        Returns a style element's reference using its name.

        If the first argument is already an element reference, it returns
        the argument if it is indeed a style element, and undef if not.

        By default, the style name is sought amongst "style" type elements
        in the "style" namespace. If an application is looking for a special
        style (e.g. page or number), then it can pass the optional
        parameters "namespace" and/or "type". See the section on createStyle
        for these concepts.

        A search is of course limited to automatic styles if the current XML
        document is content. If the document is styles, the search for the
        name is made in all styles by default. You can, however, limit it
        with the "path" parameter where "path" equals "auto" to search in
        automatic styles or "named" in named styles.
	Note: Take care of possible differences between the 'display-name'
	and the real 'name' of any style (see the DESCRIPTION of the present
	manual chapter). If you decide to select the styles by their visible
	names, set the 'retrieve_by' property of the document to
	'display-name'. Example:
		$doc->{'retrieve_by'} = 'display-name';
		my $s = $doc->getStyleElement("Text body");

=head3	getStyleList([options])

        Combines the results of getAutoStyleList and getNamedStyleList (same

=head3	importBackgroundImage(page, filename [, link])

        Imports a background image into the given page style from an
        external file.

        The page style can be either a page layout or a master page. An
        optional link can be inserted (e.g. to reuse an existing link). See
        backgroundImageLink or imageLink (in OODoc::Image) for information
        about links. Otherwise, an internal link under "Pictures/" is
        created by default and takes the name of the source file.

        Returns the link if found, undef if not.

        Caution: the actual import is not made until a save is called (see
        importImage in OODoc::Image).

=head3	importFontDeclaration(doc, fontname)

=head3	importFontDeclaration(xml_string)

	In the first form, retrieves a font declaration in another document
	and installs it in the current document. The first argument is a
	OODoc::Styles or OODoc::Document object.
		my $source = ooDocument
			file => "source.sxw", member => "styles"
		my $target = ooDocument
			file => "target.sxw", member => "styles"
		$target->importFontDeclaration($source, "Helvetica");
	In the second form, the single argument is the XML string
	containing a font declaration.

	The following example creates a declaration for the "Comic Sans MS"
	font in an OpenDocument:
		    '<style:font-face '				.
		        'style:name="Comic Sans MS" '		.
			'svg:font-family="Comic Sans MS"	.
	This last import feature is not mainly provided in order to encourage
	raw XML coding! Be careful, the XML font declaration syntax is not
	exactly the same with the two supported document formats. This feature
	should be used in order to import previously exported font declarations
	(see exportXMLElement in OODoc::XPath).   
	A font declaration must be imported if it's used in a newly
	created style and not currently available in the target document.

=head3	masterPageExtension(page, extension_type [, element])

	This method allows the user to get or set an extension to an existing
	master page. The most used extensions are "header", "footer",
	"header-left", "footer-left", but any other key could be provided
	(warning: there is no ODF-compliance check, so any application-
	specific tag is allowed, knowing that any provided keyword will be
	automatically prefixed by "style:" in the generated XML).
	See masterPageFooter(), masterPageFooterLeft(), masterPageHeader(),
	masterPageHeaderLeft(); these methods can be regarded as synonyms
	for masterPageExtension() with the four listed extension types.
=head3	masterPageFooter(page [, element])

        Returns the given page style's footer element reference (master
        page) or undef if not found.

        If the second argument is a content element, it is added to the
        footer. If the footer does not exist, it is created.

=head3	masterPageFooterLeft(page [, element])

        Returns the given page style's footer left element reference (master
        page) or undef if not found.
	A "footer left" element can be used to specify different content for
	left pages, if appropriate. Unless a footer left element is defined
	in the master page, the content of the footers on left and right pages
	is the same. 

        If the second argument is a content element, it is added to the
        footer. If the footer does not exist, it is created.
=head3	masterPageHeader(page [, element])

        Returns the given page style's header element reference (master
        page) or undef if not found.

        If the second argument is a content element, it is added to the
        header. If the header does not exist, it is created.
=head3	masterPageHeaderLeft(page [, element])

        Returns the given page style's header left element reference (master
        page) or undef if not found.
	A "header left" element can be used to specify different content for
	left pages, if appropriate. Unless a header left element is defined
	in the master page, the content of the headers on left and right pages
	is the same. 

        If the second argument is a content element, it is added to the
        header. If the header does not exist, it is created.

=head3	pageLayout(master_page [, page_master])

        Returns or modifies the layout of a given page style (master page).
	If the second argument is given, it replaces the old page layout value
	(i.e. it changes the layout of the page without changing the header or
	footer content.

=head3	pageMasterStyle(master_page [, page_master])

	See pageLayout()

=head3	removeStyleElement(style [, options])

        Deletes the given style. The argument and options are the same as
        for getStyleElement. The method returns "True" (1) if successful or
        undef if the style is not found.

=head3	selectStyleElementByFamily(family [, options])

        Returns the first (or only) available style in the given family
        (using the "family" attribute), or undef if not found. Options are
        the same as for getStyleElement.


            my $style = $doc->selectStyleElementByFamily
            		type	=> 'default-style'

        selects the element which describes the default graphic style.

        This method is useful for selecting styles whose "family" attribute
        is their identifier (and which do not have a "name" attribute). For
        example, this is the case for default styles where there is normally
        a default style for the "paragraph" family and another for the
        "graphics" family. In the above example, we used the "type" option
        where the type is "default-style" and not "style". We did not use
        the "namespace" option because it would be pointless to know that
        the default style namespace is just the default namespace ("style").

=head3	selectStyleElementsByFamily(family [, options])

        Like selectStyleElementByFamily but returns a list of elements which
        belong to the given family. The "family" argument is treated as a
        regular expression, so an application must therefore give the
        appropriate meta-characters if the search is to be limited to the
        exact family name.

=head3	selectStyleElementsByName(name [, options])

        Returns a list of styles whose names match the first argument (which
        is treated as a regular expression). Options are the same as for the
        other selectStyleElementsXXX methods.

=head3	setBackgroundImage(page, options)

        Inserts or replaces a background image in a page style. The "page"
        argument points either to the page layout directly, or to the master
        page to which it refers. Options point to the graphics object and
        how it is presented. The returned value is the created or modified
        background image's element reference (see

        You should first indicate the graphics file which contains the image
        and whether it will merely be linked to the page by reference, or if
        it has to be physically imported into the OpenOffice.org file. To
        "link" the image, you supply its address using the "link" option. To
        import it, you supply the image using the "import" option.


            	"First page",
            	import		=> "C:\Images\Logo.jpg"

            	"First page",
            	link		=> "C:\Images\Logo.jpg"

        These two calls produce the same effect, but the second only inserts
        a link to the image.

        Remember that if by error an application supplies both the "link"
        and "import" options, the "import" option is the one that prevails.

        The other options control the import of images as backgrounds. By
        default, OODoc::Styles installs the image in the center without
        tiling and with an automatic update-on-load attribute if the image
        is by external link. You can choose other options using the
        OpenOffice.org standard vocabulary.

        To link a background image which is stretched to fit the entire
        page, use the following:

            	"First page",
            	link		=> "C:\Images\back.jpg",
            	'style:repeat'	=> 'stretch'

=head3	styleName(style_element [, name])

=head3	styleName(name [, options])

        The first form checks that the given argument is indeed a "style"
        element reference and, if it is, returns its name (undef if not). If
        a name is given as the second argument, it replaces the style name.

        In the second form, the current style name is given. In this case,
        and without any other arguments, the method only checks if the given
        name is indeed a style and returns a positive result (undef if not).
        It is still possible to change its name using this form, by using
        the "newname" option. With this form, some other options allow you
        to choose the namespace, type and category (automatic or named).
        These options are "namespace", "type" and "category" (see
        getStyleElement for these concepts). Without these parameters, the
        default values are the same as for getStyleElement.

=head3	styleProperties(style [, options])

        This method is for checking and updating the formatting properties
	of a given style.
        It is more limited than updateStyle, but easier to code. The
        styleProperties method accesses only the style's formatting
	attributes and does not touch its references, such as its name, class
	or family (see getStyleAttributes).

        With no options, the current style's properties are simply returned
        in the form of a hash in which the keys are attributes belonging to
        the OpenOffice.org standard vocabulary and which depend on the type
        of object. The same data structure can be used to modify a style's
        properties by passing options as a hash. This structure is the same
        as the sub-hash "properties" of getStyleAttributes or updateStyle.
        If you wanted to redo the style we called "Colour" (see createStyle),
	for example, changing the colour of the characters to red and
	replacing the italics with standard font, you could do it as follows:

			'-area'		=> 'text',
            		'fo:color'	=> rgb2oo("red"),
            		'fo:font-style'	=> undef

        This short sequence sets the "fo:color" attribute to red and clears
        the "font-style" attribute. Remember that in RGB notation, the
        quantity of red is given by the first two hexadecimal digits, which
        here are set to maximum, and by setting the green and blue to zero.
        The "font-style" attribute had previously been set to "italic".
	Here, the 'area' option is neutral if the document format is OOo,
	but it must be set to 'text' for an ODF document, because all that
	is related to characters belongs to the 'text' area in a paragraph
	style (see below).

        styleProperties returns all the style's properties but only modifies
        those that have been set using options. To clear an existing
        property without giving it a new value, you must pass the
        corresponding option giving it a null value.

	If the current document is an OASIS Open Document, an additional
	"-area" option should be provided, because a style's properties may
	be stored in logical parts. For example, in a paragraph style, some
	properties apply to the paragraph itself, while some other ones apply
	to its text content (and some text properties can have the same name
	as some paragraph properties). The default value is the name of the
	style family. For example, if the style family is "paragraph", the
	"paragraph" part is selected by default. Because it updates font
	attributes (that are text properties), the example above couldn't
	work against an Open Document without an additional "area" option
	with the appropriate value:

			'-area'		=> 'text',
            		'fo:color'	=> "#ff0000",
            		'fo:font-style'	=> undef

	After creating a new paragraph style in an Open Document, this method
	should be used in order to set the properties which have not been set
	by createStyle because of the separation in two areas. In the
	following example, the 'paragraph' properties are directly set with
	createStyle, then the 'text' properties are set with styleProperties:
		my $style = $doc->createStyle
			family		=> 'paragraph',
			parent		=> 'Standard',
			properties	=>
				'-area'			=> 'paragraph',
				'fo:text-align'		=> 'center',
				'fo:margin-left'	=> '0.5cm',
				'fo:margin-right'	=> '0.5cm'
			$style, '-area' => 'text',
			'fo:color'		=> oo2rgb("blue"),
			'fo:font-weight'	=> 'bold',
			'style:font-name'	=> 'Times New Roman'
	Note: According to the OASIS OpenDocument v1.0 specification,
	any arbitrary custom attribute could be created in anyone of the
	style's properties area, and *should* be preserved by conforming
	applications when editing the document. However, up to now, any
	custom property is lost as soon as the document is edited through
	The "-area" option is silently ignored with OOo 1 documents.
=head3	switchPageOrientation(page)

        Switches a portrait page to landscape and vice-versa.

        The argument is a page style (page layout or master page).

	'portrait' and 'landscape' are not style properties. The logic of
	this method is very simplistic: it makes a swap between the height
	and the width of the page.

	CAUTION: don't try to give a page number as the argument. This
	method apply on a page style (i.e. master page) and not on a
	real page selected by its number.

=head3	updateDefaultStyle(family, options)

        Modifies the default style for the given family according to an
        options hash given by the application. The family is generally
        "paragraph" or "graphics".

        Options are given according to the OpenOffice.org style attributes

        The following example shows how to change the font, font size and
        default tab stops in the text:

            	'fo:font-name'			=> 'Helvetica',
            	'fo:font-size'			=> '10pt',
            	'style:tab-stop-distance'	=> '1.5cm'

=head3	updateOutlineStyle(level, properties)

=head3	updateOutlineStyle(outline style element, properties)

	Allows any change in the direct attributes of an outline style.
	The new properties must be provides through a hash, where each key
	is an OpenDocument-compliant attribute.
	The following example changes the numbering prefix and suffix, and
	the numbering format for the level 1 list elements, so their numbering
	will look like "[A] ", "[B] ", "[C] ", ...
			'num-prefix'		=> "[",
			'num-suffix'		=> "] ",
			'num-format'		=> "A"
	See the OpenDocument specification for the full set of possible
	attributes. Any attribute provided without namespace prefix (i.e.
	not including a ':'), such as those in the example above, are
	automatically prefixed by 'style:'; other attributes must be provided
	with their prefixes.
	Caution, some outline presentation characteristics, such as bullet
	style, are not directly under the control of this element. They depend
	on children "style:*-properties" elements.

=head3	updatePageLayout(page, options)

        Modifies all types of page presentation style characteristics (page
        master). The style given as the first argument can be either the
        appropriate page layout style directly, or a page style (master
        page) to which it refers.

        Options can be passed in the form of a hash of hashes (each option
        itself points to a hash containing the base attributes). The four
        top-level elements are as follows:

            references		=> name, family, etc.
            properties		=> global presentation attributes
            header		=> header presentation style
            footer		=> footer presentation style
            footnote-sep	=> footnote separator style
            background-image	=> backgrnd.jpg image characteristics

        The "references" branch will not generally be used unless you want
        to change the style's name.

        This data structure is the same as returned by
        getMasterPageAttributes(). A combination of these two methods allows
        you to copy the characteristics of one page style to another easily,
        especially when you want to apply the page setup of one document to
        another. When you only want to modify an existing style however, you
        only need to specify the attributes which you want to change.

        A "prototype" option allows you to clone the characteristics of an
        existing page layout. This option can indicate either an existing
        page layout reference, its logical name, or even the reference or
        logical name of a master page which refers to it. Only the first
        method is supported if the prototype page layout belongs to another
        document. The style name is not replaced by the prototype style
        name. See also createStyle about using a prototype style.

        The following example shows the code required to change several
        properties of the "Right page" style i.e. top margin width,
        background colour, maximum footnote height, minimum header height
        and the colour and width of the footnote separator.

            	"Right page",
            	properties	=>
            	 'fo:margin-top'		=> '2.5cm',
            	 'fo:background-color		=> '#88eecc',
            	 'style:footnote-max-height'	=> '3cm'
            	'footnote-sep'	=>
            	 'style:width'			=> '0.02cm',
            	 'style:color'			=> '#0000ff'
            	header		=>
            	 'fo:min-height'		=> '2cm'

        Once again, it is better to start with a getMasterPageAttributes()
        of an existing page than to create all your styles from code.

=head3	updatePageMaster(page, options)

	See updatePageLayout()

=head3	updateStyle(style, options)

        Modifies the characteristics of an existing style.

        Options are the same as for createStyle() except for "category",
        "namespace" and "type" which cannot be changed in an existing style
        since they form part of its basic identity. A style's logical name
        can, however, be changed.
	The first argument can be either a style name or a style element.
	The second way should be preferred when the program already owns
	the element (obtained, for example, through getStyleElement() or

	In the 'properties' structure, the 'area' switch is required with
	ODF (OOo 2) documents if the property area is not the default one
	(see styleProperties and createStyle about the 'area' option). 

        You can use the "prototype" option to update a style with another
        style's characteristics, but this option does not replace the
        style's name with the prototype's name. Be careful, the "prototype"
	option doesn't work for any kind of style, and it's not recommended
	in this method. The best approach for replicating an existing style
	consists of creating a new style with the "prototype" option (see

        By definition, the style already exists and can be indicated equally
        well by reference or by name.

        Returns the characteristics of the modified style, as in

=head2	Exported functions

=head3	odfColor(rgb_color)

	Converts an RGB color code or name into an ODF-compliant color code.
	See rgb2oo().

=head3	ooLoadColorMap($filename)

	Populates the %OpenOffice::OODoc::Styles::COLORMAP hash from the
	content of an RGB file. This file defines a colour dictionary.
	Without argument, the content of the $COLORMAP variable is considered
	as the filename.

	Each line must contain 4 space-separated fields. The 3 first fields
	represent, respectively, the red, green and blue values of a colour
	and must be positive integer values in the 0-255 range. The remainder
	of the line is considered as the symbolic name of a colour (it can
	contain spaces). Example:

		144 238 144	light green
		139   0 139	dark magenta
		255 105 180	hot pink
		255  99  71	tomato

	Such a file is sometimes provided in a system directory (for example
	/usr/lib/X11/rgb.txt in some Unix systems). In any case, the users
	can easily find and download it somewhere. For example, a convenient
	rgb.txt file is provided with the Color::Rgb Perl module (CPAN).

	When a COLORMAP is loaded, the programmer can provide symbolic, user-
	friendly names in place of RGB values to the rgb2oo() function.
	Without argument, the content of the $COLORMAP variable is considered
	as the filename.

	When the OpenOffice::OODoc::Styles module is loaded as a consequence
	of a "use OpenOffice::OODoc" statement, ooLoadColorMap() is
	automatically executed if a valid filename is provided in the
	<Styles-COLORMAP> element of the "OODoc/config.xml" file.

=head3	oo2rgb($oocolor)

	Returns the conventional RGB value of an OOo-encoded colour.

	In array context, returns a 3-element array containing the red, green,
	blue decimal values of the colour.

	In scalar context, returns either a string with concatenated, comma
	separated red, green, blue values, or, if these values exactly match
	a known colour (according to the current %COLORMAP), the corresponding
	symbolic name.

	This function can be used to display or compute separately the RGB
	values of any colour attribute of a style, or to export these values
	to an image processing software. It produces the same result as the
	hex2rgb() method of the Color::Rgb Perl module.

=head3	rgb2oo($red, $green, $blue)
=head3	rgb2oo("$red,$green,$blue")
=head3	rgb2oo($colorname)

	Converts an RGB or named colour in ODF-compliant hexadecimal format
	(6 digits after a leading '#'). The 1st form has the same effect as
	the rgb2hex() function of the Color::Rgb Perl module.

	The resulting value can be used to set any colour attribute in a

	In the first form, the 3 arguments are the conventional numeric RGB
	values (between 0 an 255). In the second form, the only one argument
	is a string containing the comma-separated RGB values. In the third
	form, the given string is the symbolic name of a colour (the name
	must be an existing one in the %COLORMAP hash).


                 	'fo:color'		=> rgb2oo('black'),
                 	'fo:background-color'	=> rgb2oo('yellow')
	If the argument seems to be already an hexadecimal RGB string (i.e.
	it begins by "#"), rgb2oo() checks it and returns it unchanged if
	it's a regular RGB value, or undef if not.

=head3	rgbColor(odf_color)

	Converts an ODF-color code into a decimal RGB code or, according
	to a mapping file, into a plain text conventional color name.
	See oo2rgb().
=head2	Properties

	The 'retrieve_by' option, set to 'display-name', can be provided
	in order to select the style elements by their display name instead
	of their primary name (names and display names are introduced in the
	beginning of this manual chapter).

	The %COLORMAP hash, defined as a class variable, contains a name
	to RGB translation table. When loaded, it allows the rgb2oo() function
	to use symbolic names in place of RGB values.
	The keys are symbolic, user-defined colour names, and the values are
	strings containing the concatenated, comma-separated RGB values.


	%OpenOffice::OODoc::Styles::COLORMAP{'antique white'} = "250,235,215";

	By default, this hash contains a short, arbitrary set of colour
	definitions such as 'red', 'green', 'blue', 'white', 'black' and a few
	others. The user can populate it from an external RGB file, through
	the ooLoadColorMap() function previously described, and/or through
	program instructions like the example above.


Developer/Maintainer: Jean-Marie Gouarne L<http://jean.marie.gouarne.online.fr>

Contact: jmgdoc@cpan.org

Copyright 2004-2006 by Genicorp, S.A. L<http://www.genicorp.com>

Initial English version of the reference manual by Graeme A. Hunter


	- Licence Publique Generale Genicorp v1.0
	- GNU Lesser General Public License v2.1