OODoc::Styles(3pm)
OODoc::Styles(3pm) 💅✨
User Contributed Perl Documentation — folded in near the top because we're not doing that boring header line, bestie. 🎀
💖 NAME 💖
OpenOffice::OODoc::Styles — Document styles and layout processing
🌸 DESCRIPTION 🌸
okay so this class? It's the style whisperer 💅 It handles styles — automatic or named — living in styles.xml or content.xml. It inherits from the common OpenOffice::OODoc::XPath class and brings style-focused features. Iconic.
Do not use this class directly in an ordinary application, bestie, because every feature it has is available in the OpenOffice::OODoc::Document class, combined with other features. Practically, this 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. So like, it's the backstage crew, not the main character you call. 🫶
Remember that named styles are those the end user can see and edit through the GUI of interactive office software (for example, 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). On 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 a method such 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). periodt.
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. no cap.
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. Some styles are more complex than others as they describe the page layout. A page style, 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. It's giving web of vibes, not a simple list.
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". iykyk.
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. thank u, next. 💅
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 select the associated page layout. So forgiving. 🧚
OODoc::Styles allows the applications to create new styles, and not only to update existing styles. However, 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 OpenDocument specification. As a consequence, building styles from scratch by program is not a recommended practice. It's much more easy to create documents with all the needed styles through an ODF-compliant office software, and to use them as templates in the programs, knowing that it's very easy to retrieve an existing style, to copy it and to re-use it (as is or customised) in new documents. work smarter, not harder. ✨
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. periodt.
✨ Methods ✨
🎀 Constructor : OpenOffice::OODoc::Styles->new(<parameters>) 🎀
- Short form:
odfStyles(<parameters>) - This constructor should not be explicitly used in ordinary applications, knowing that all the features of the returned object are inherited by any
Documentobject. - See
OpenOffice::OODoc::XPath->new()for common arguments. - Returns an
OODoc::XPathOpenDocument 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"part should be forced if the application is to work with styles associated with the document body (automatic styles only).
🖼️ 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.
Example:
$doc->backgroundImageLink
("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.
👑 createMasterPage(name, options) 👑
Creates a new page style. Options are:
'layout' => page layout name
'next' => next master page style nameThe association with a "page layout" allows you to associate a layout to the page. Otherwise the page will have a default layout.
Example:
$doc->createMasterPage
(
"MyPageStyle",
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.
📐 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().
✨ createPageMaster(name, options) ✨
See createPageLayout() — that's the whole assignment, bestie 💅
✨ createStyle(name, options) ✨
Creates a new style of any type or class (depending on options) and returns its reference if successful. Slay. ✨
The first argument indicates the new style name which must be unique in the document. By default, there is no automatic uniqueness check. However, if a 'check' option is set to 'true', the method fails and produces an error message warning if the style already exists. So if you're paranoid, turn that on. 👀
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. iykyk.
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 part, 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. Don't fight it, it's automatic. 💅
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 notes configuration style (called "text:notes-configuration" in the ODF specification), you will have to specify the "notes-configuration" type explicitly in the "text" namespace using one of the following two options:
namespace => 'text',
type => 'notes-configuration'The possible options are:
namespace => namespace— the namespace, obvitype => style type— the style typefamily => style family (text, paragraph, ...)— style family, liketext,paragraph, ...class => style class— style classparent => parent style (inherit)— parent style, inherit from itnext => next style— 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 specify it into terms of 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 is a hash provided by the application. It's giving very main character energy. 👑
Here is an example of a paragraph style creation
$doc->createStyle
(
"Colour",
family => 'paragraph',
parent => 'Standard',
properties =>
{
'fo:margin-left' => '2cm',
'fo:margin-right' => '1.5cm',
'fo:text-align' => 'justify',
'fo:background-color' => '#ffff00'
}
);
$doc->setStyle($doc->getParagraph(3), "P3");This sequence gives paragraph 3 of the document a special style whose properties are given margins, text justification and a yellow background color (note that the ODF color codes are in RGB hexadecimal preceded by a '#', and 'ffff00' is the RGB value for for the yellow color). This is done using a style called "Colour" (reusable later for other paragraphs) based on the "Standard" style. The names of the properties can be found in the ODF specification (some of them come from the Form Object standard, so they begin with the "fo:" prefix). However, the given properties are related to the global layout of the paragraph. We could provide this new style with additional properties related to the text content of the paragraph. But, in a paragraph style definition, the "text" properties are not stored in the same logical area than the "paragraph" properties, and we can't set both in the same instruction. Fortunately, we can enrich any existing style at any time through the updateStyle() method:
$doc->updateStyle
(
"Colour",
properties =>
{
-area => 'text',
'style:font-name' => 'Times',
'fo:font-size' => '14pt',
'fo:font-weight' => 'bold',
'fo:font-style' => 'italic',
'fo:color' => '#000080'
}
);This new sequence gives paragraph 3 (or any paragraph using the "Colour" style) a lovely Times font in dark blue size 14 bold italics. The '-area' parameter which appears in the 'properties' hash is not a property; it's a selector which instructs the API to select the "text" property set. So fancy.
Note: the hexadecimal color codes used in the example could be replaced by more user-friendly color names, according to a standard or application-specific RGB color table, through the odfColor() function introduced in the present manual chapter. Glow up your colors. 🌈
If the '-area' selector is omitted, the property set whose name is the name of the style family (i.e. 'paragraph' in the last example).
The '-area' selector 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. Just know they might ghost you later. 👻
Another example:
$doc->createStyle
(
"Photo1",
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. Chlorophyll? More like bore-ophyll, but okay. 🌿
Note: In the given examples, "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.) No cap.
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). It's giving adaptable.
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. But there is no persistent link from the new style to its prototype. No strings attached, periodt. 💖
Example:
$doc->createStyle
(
"Bigger",
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. Iconic behavior. ✨
The given "parent" style is not necessarily defined yet and, if the current document part is "content", it can be the name of a style defined in the "styles" member. (See getAncestorStyle() and getParentStyle()).
Generally speaking, explicit parameters passed by an application (e.g. font size) prevail over prototype's parameters. So your choices win. As they should. 💅
The prototype parameter can be a style name (like in that example up there) or a whole style element. If it's an element, honestly, where it came from doesn't matter at all — it can totally be a copy of a style element you yoinked out of some other document earlier. If it's a name, though, the prototype style gets fetched either from the current document (that's the default, bestie) or, if you pass the 'source' option, from a different document.
The value of the 'source' option is another OODoc::Styles (or OODoc::Document) object. Give it that option and createStyle goes looking in the document you pointed at for the prototype style. And if you provide 'source' but not 'prototype', then the prototype style is assumed to have the exact same name as the style you're creating. ✨
So say you wanna create a style called "MyStyle" in document $doc1 that imitates a style called "HisStyle" over in document $doc2 (both of those being OODoc::Styles or OODoc::Document objects) — you'd do this:
$doc1->createStyle
(
"MyStyle",
prototype => "HisStyle",
source => $doc2
);But if you write
$doc1-createStyle
(
"MyStyle",
source => $doc2
);then the local style "MyStyle" is built as a copy of the style with that same name in the source document. It's a direct import, periodt.
Whatever the origin of that prototype style is, literally any property can be set or redefined in the new style. 💅
And it's not just importing styles that live in other documents — you can also create automatic styles in a 'content' part that are derived from named styles found in the 'styles' member, and vice-versa. Full circle moment.
WARNING: the "prototype" option can produce unexpected results if the two documents aren't in the same format. So using an OOo 1 style as the prototype of an OpenDocument one (and vice-versa) should be avoided. 🚫
Always be careful about dependencies, okay? There are often dependencies between styles. An application has to be wary of importing styles that have direct or indirect dependencies on other styles which won't be available in the target document. Text styles are pretty easy to control this way, but table, page and graphic styles, for example, have way more complex dependencies. 😭
When a font name gets set (generally through a 'style:font-name' text property) in a new style, take care of whether the corresponding font declaration is actually available 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 easiest (and least error-prone) way is to create template documents through the OpenOffice.org GUI (or any other ODF-compliant office software) and use those as style libraries. 🎀
exportBackgroundImage ✨
exportBackgroundImage(page [, destination])Exports the graphics file that corresponds to a page style's background image — but only where that image exists and is internal to the OpenOffice.org archive. (A linked image is obviously not exportable, since it's literally not present in the document.) Peep the exportImage method in OODoc::Image for the export details.
Example:
$doc->exportBackgroundImage
("First Page", "C:\Images\backgrnd.jpg");getAncestorStyle 🧚
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 its own 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 part.
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 ODF document, there are 2 possible situations:
- 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 via the "styles" member, if we currently work with the "content" member).
Beware: the returned name is the main name (identifier), and not the display name. 👀
See also getParentStyle().
getAutoStyleList 🌈
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 a list of number styles (namespace "number", type "number-style"), do it like this:
my @styles = $doc->getAutoStyleList
(namespace => 'number', type => 'number-style');getAutoStyleRoot 🦋
getAutoStyleRoot()Returns the element that contains all the automatic style elements. It's giving root energy.
See also getNamedStyleRoot().
getBackgroundImageAttributes 💖
getBackgroundImageAttributes(page)Returns the attributes of the given page style's background image (if any), in the form of a hash (attribute => value).
getBackgroundImageElement 🌸
getBackgroundImageElement(page)Returns the element reference of the given page style's background image (if found).
getDefaultStyleAttributes ⭐
getDefaultStyleAttributes(default_style)Returns the given default style's attributes (if any). Default styles are generally "paragraph" and "graphics". See also updateDefaultStyle().
getDefaultStyleElement 👑
getDefaultStyleElement(family)Returns the default style element's reference, given by its logical name.
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");getFontDeclaration 🔥
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.
Example:
unless ($doc->getFontDeclaration("Times New Roman"))
{
$doc->importFontDeclaration($doc2, "Times New Roman");
}See also importFontDeclaration().
getFontDeclarations 💜
getFontDeclarations()Returns the full list of the font declaration elements present in the document.
The following example prints every declared font name:
foreach my $fd ($doc->getFontDeclarations)
{
print $doc->getFontName($fd) . "\n";
}getFontName 🍓
getFontName(font_decl)Returns the name of the given font declaration element.
Returns the argument as-is if that argument is the name of a declared font, or undef if the name is unknown.
getFooterParagraph 😭
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 — because printable pages are dynamically created by the office software and literally don't exist in the stored document. 💀
getHeaderParagraph 🙈
getHeaderParagraph(masterpage, number)Like getFooterParagraph, but for a header. Same vibe, different end of the page.
getMasterPageElement 🎀
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 that case, the method's job is simply to check whether 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 this manual chapter for a few explanations about master pages (and, of course, feel free to dig into the OpenDocument specification for details).
This method should preferably be used on the 'styles' member; it doesn't generally make sense with the 'content' member, since master pages are generally described as named styles.
getMasterStyleList 🌟
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 namespace.
Like getMasterPageElement(), this method makes more sense on 'styles' members than on 'content' ones.
getMasterStyleRoot 💫
getMasterStyleRoot()Like getNamedStyleRoot(), but the returned element contains the master style descriptors instead.
getNamedStyleList 🫶
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. Not a single one. Empty. Periodt.
getNamedStyleRoot 🧚♀️
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. reuse era 💖
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().
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. ✨
getPageMasterAttributes(page)
See getPageLayoutAttributes().
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 master. 🎀
getPageMasterElement(page)
See getPageLayoutElement().
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 name, if any, is the identifier of the parent style, which can differ from its display name.
The returned parent name can be the name of a style defined elsewhere (or not defined yet). no cap, it can literally not exist yet 🙈
See also getAncestorStyle().
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. main character energy tbh 💅
getStyleElement(style_name [, options])
Returns a style element's reference using its name, or undef if no style owns the given name in the current context. Remember that a style can be used in the 'content' context while its descriptor (i.e. the style element) is defined in either the 'styles' context or the 'content' one. If the application doesn't know where the needed style is defined, it must call getStyleElement() in both. both!! don't skip!!
If the first argument is already an element reference, it returns the argument if it is indeed a style element, and undef if not, so this method could be used in order to check if a given element is a style element or not. glow-up as a type-check ✨
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.
The name is a mandatory property, and the main identifier of any style in ODF-compliant documents. But an additional property, so-called 'display-name', is sometimes provided by the applications. The 'display-name' property, if provided, is made visible for the end user by the office software (for example in the stylist box of OpenOffice.org) while the primary name is hidden. By default, getStyleElement() looks for a style whose primary name matches the given name, then, if the query fails, it tries to retrieve the style according to its display name. However, if the "retrieve_by" property of the connector is set to 'display-name', the display name becomes the preferred identifier. two names, one style, iconic behaviour 👑
If a "retry" parameter is provided and set to "false" or any other value than "1" or "true", no double query is done. In other words, if the first query (by primary name or by display name, according to the value of the "retrieve_by" property of the connector) fails, the method returns immediately without trying any other query. The default value is "1" (true). You should set it to "0" or "false" in order to save some computation time if, for example, your application doesn't need to take care of the possible differences between display names and internal names. performance bestie 🏃♀️
getStyleList([options])
Combines the results of getAutoStyleList and getNamedStyleList (same options). both lists, one vibe
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 (seeimportImageinOODoc::Image). fr fr, nothing happens until you save!! 😭
importFontDeclaration(doc, fontname)
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.
Example:
my $source = odfDocument
(
file => "source.odt", part => "styles"
);
my $target = odfDocument
(
file => "target.odt", part => "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:
$doc->importFontDeclaration
(
'<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). raw XML girlies, stay calm 🫶
A font declaration must be imported if it's used in a newly created style and not currently available in the target document.
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). no compliance check bestie, it's the wild west 💀
See masterPageFooter(), masterPageFooterLeft(), masterPageHeader(), masterPageHeaderLeft(); these methods can be regarded as synonyms for masterPageExtension() with the four listed extension types.
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. auto-creation, we love her ✨
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.
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.
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. left pages stay getting special treatment 🦋
If the second argument is a content element, it is added to the header. If the header does not exist, it is created.
pageLayout(master_page [, page_master])
So this one either hands you back the layout of a given page style (that's your master page, bestie 💅) or it rewrites it. Hand it that second argument and the old page layout value gets straight-up replaced — which means you've changed how the page lays out without touching the header or footer content. Iconic, honestly.
pageMasterStyle(master_page [, page_master])— just go peeppageLayout()bestie, it's giving the exact same energy. 🫶removeStyleElement(style [, options])— deletes the style you point it at. The argument and the options are literally the same as forgetStyleElement. It returns"True"(1) if it worked out, orundefif that style just isn't there. 😭selectStyleElementByFamily(family [, options])— gives you back the first (or only) style chilling in the family you named (it goes off the"family"attribute), orundefif there's nothing to find. The options are the same as forgetStyleElement.
Example:
my $style = $doc->selectStyleElementByFamily
(
"graphics",
type => 'default-style'
);...which selects the element describing the default graphic style. Slay. ✨
This one is so handy for picking out styles whose "family" attribute is their identifier (aka the ones that don't have a "name" attribute). Like, this is exactly the case for default styles, where you've normally got one default style for the "paragraph" family and another one for the "graphics" family. In the example up there we used the "type" option with the type set to "default-style" and not "style". And we did not use the "namespace" option, because knowing that the default style namespace is just the default namespace ("style") would be completely pointless. Periodt.
selectStyleElementsByFamily(family [, options])— same vibe asselectStyleElementByFamilybut it hands you back a whole list of elements that belong to the given family. Heads up though: the"family"argument gets treated as a regular expression, so if you want the search limited to the exact family name you've gotta supply the right meta-characters yourself. No cap. 🦋selectStyleElementsByName(name [, options])— returns a list of styles whose names match that first argument (which is, again, treated as a regular expression). Options are the same as for all the otherselectStyleElementsXXXmethods.setBackgroundImage(page, options)— inserts or replaces a background image in a page style. The"page"argument points either straight at the page layout, or at the master page that it refers to. The options point at the graphics object and at how it gets presented. What you get back is the created-or-modified background image's element reference (go seegetBackgroundImageElement). 🌸
First thing you wanna do is say which graphics file holds the image, and whether it's just gonna be linked to the page by reference or whether it has to be physically imported into the OpenOffice.org file. To "link" the image, you supply its address with the "link" option. To import it, you supply the image with the "import" option.
Examples:
$doc->setBackgroundImage
(
"First page",
import => "C:\Images\Logo.jpg"
);
$doc->setBackgroundImage
(
"First page",
link => "C:\Images\Logo.jpg"
);These two calls produce the same effect, but the second one only inserts a link to the image. 🎀
Remember: if by error an application supplies both the"link"and the"import"options,"import"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 pick other options using the OpenOffice.org standard vocabulary.
To link a background image that's stretched to fit the entire page, do this:
$doc->setBackgoundImage
(
"First page",
link => "C:\Images\back.jpg",
'style:repeat' => 'stretch'
);styleName(style_element [, name])styleName(name [, options])— okay so there's two forms and they're lowkey different, stay with me. 💜
Form one: it checks that the argument you gave really is a "style" element reference and, if it is, returns its name (undef if it isn't). Give a name as the second argument and it replaces the style name.
Form two: here you hand over the current style name. In this case, with no other arguments, the method just checks whether that name is actually a style and returns a positive result (undef if not). You can still change its name in this form too, using the "newname" option. In this form, some other options let you choose the namespace, type and category (automatic or named) — those options are "namespace", "type" and "category" (peep getStyleElement for those concepts). Without those parameters, the defaults are the same as for getStyleElement.
Beware bestie: the only recognized style name here is the main style name, which can differ from the display name. 🙈
styleProperties(style [, options])— this method is for checking and updating the formatting properties of a given style.
It's more limited than updateStyle, but easier to code. styleProperties only touches the style's formatting attributes and never messes with its references, like its name, class or family (see getStyleAttributes).
With no options, the current style's properties just get returned as a hash, where the keys are attributes from the OpenOffice.org standard vocabulary and they depend on the type of object. That same data structure can be used to modify a style's properties by passing options as a hash. It's the same structure as the "properties" sub-hash of getStyleAttributes or updateStyle.
Say you wanted to redo the style we called "Colour" (see createStyle) — like, change the colour of the characters to red and swap the italics out for a standard font — you'd do it like this:
$doc->styleProperties
(
"Colour",
'-area' => 'text',
'fo:color' => odfColor("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 amount of red is given by the first two hexadecimal digits — here they're set to maximum — and by setting 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 everything related to characters belongs to the 'text' area in a paragraph style (see below). ✨
styleProperties returns all the style's properties but only modifies the ones you set with options. To clear an existing property without giving it a new value, you've gotta pass the corresponding option with a null value.
If the current document is an OASIS Open Document, you should also provide an extra "-area" option, 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 others apply to its text content (and some text properties can share a name with some paragraph properties). The default value is the name of the style family — so if the style family is "paragraph", the "paragraph" part is selected by default. And because it updates font attributes (which are text properties), the example above couldn't work against an Open Document without an extra "area" option with the appropriate value:
$doc->styleProperties
(
"Colour",
'-area' => 'text',
'fo:color' => "#ff0000",
'fo:font-style' => undef
);After creating a new paragraph style in an Open Document, this method should be used to set the properties that createStyle didn't set, because of the separation into two areas. In the following example, the 'paragraph' properties get set directly with createStyle, then the 'text' properties get set with styleProperties:
my $style = $doc->createStyle
(
"CenteredStyle",
family => 'paragraph',
parent => 'Standard',
properties =>
{
'-area' => 'paragraph',
'fo:text-align' => 'center',
'fo:margin-left' => '0.5cm',
'fo:margin-right' => '0.5cm'
}
);
$doc->styleProperties
(
$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 any one of the style's properties areas, 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 OpenOffice.org. 💀
Also: the "-area" option is silently ignored with OOo 1 documents. Just so you know. 💅
switchPageOrientation(page)— switches a portrait page to landscape and vice-versa. The argument is a page style (a page layout or a master page). 🦋
'portrait' and 'landscape' are not style properties, bestie, don't come for me. The logic of this method is very simplistic: it literally just swaps the height and the width of the page. That's it. That's the whole vibe. 🦋
CAUTION: do not try to give a page number as the argument. This method applies to a page style (i.e. a master page), not to a real page you picked out by its number. They are not the same thing and you will be sad. 😭
updateDefaultStyle(family, options)
Modifies the default style for the given family, according to an options hash that the application hands over. The family is generally "paragraph" or "graphics". ✨
Options get given according to the OpenOffice.org style attributes vocabulary.
The following example shows how to change the font, font size and default tab stops in the text:
$doc->updateDefaultStyle
(
"paragraph",
'fo:font-name' => 'Helvetica',
'fo:font-size' => '10pt',
'style:tab-stop-distance' => '1.5cm'
);updateOutlineStyle(level, properties)
updateOutlineStyle(outline style element, properties)
Allows any change in the direct attributes of an outline style. 🎀
The new properties must be provided 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] ", ...
$doc->updateOutlineStyle
(
1,
'num-prefix' => "[",
'num-suffix' => "] ",
'num-format' => "A"
);See the OpenDocument specification for the full set of possible attributes. Any attribute provided without a namespace prefix (i.e. not including a ':'), such as those in the example above, gets 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. iykyk. 🙈
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 characteristicsThe "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 getPageLayoutAttributes(). 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.
$doc->updatePageLayout
(
"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 getPageLayoutAttributes() of an existing page than to create all your styles from code. Trust. 💜
updatePageMaster(page, options)
See updatePageLayout(). That's the whole entry. Slay. ✨
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 createStyle()).
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 createStyle). 🧚
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 getStyleAttributes.
🌈 Exported functions 🌈
odfColor($red, $green, $blue) =head3 odfColor("$red,$green,$blue")
=head3 odfColor($colorname)
Converts an RGB or named colour into 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 style.
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 3 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).
Example:
ooLoadColorMap("D:\MyDocuments\Colors.txt");
$doc->styleProperties
(
"HighColors",
'fo:color' => odfColor('black'),
'fo:background-color' => odfColor('yellow')
);If the argument seems to be already a hexadecimal RGB string (i.e. it begins by "#"), odfColor() checks it and returns it unchanged if it's a regular RGB value, or undef if not. 👑
Synonym: rgb2oo().
odfLoadColorMap($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 tomatoSuch 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 odfColor() 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. ⭐
oo2rgb($oocolor)
Returns the conventional RGB value of an OOo-encoded colour.
See rgbColor(). 💅
ooLoadColorMap($filename)
Synonym of odfLoadColorMap(). 💜
rgb2oo($red, $green, $blue) =head3 rgb2oo("$red,$green,$blue")
=head3 rgb2oo($colorname)
See odfColor(). 🦋
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.
In array context, returns a 3-element array containing the red, green, blue decimal values of the colour. 🎀
In scalar context, it returns either a string with concatenated, comma separated red, green, blue values, or — if those 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. ✨
rgbColor() is a synonym of oo2rgb(). 🫶
💖 Properties 💖
The 'retrieve_by' option, set to 'display-name', can be provided in order to use the display name instead of the primary name as the first style identifier. 👑
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. 🎀
Example:
%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. 💅
👑 AUTHOR/COPYRIGHT 👑
Developer/Maintainer: Jean-Marie Gouarne <http://jean.marie.gouarne.online.fr>
Contact: jmgdoc@cpan.org
Copyright 2004-2009 by Genicorp, S.A. <http://www.genicorp.com>
Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk).
License: GNU Lesser General Public License v2.1
okay bestie, that's the whole vibe. this page came from perl v5.34.0, dated 2022-06-16, and it's OODoc::Styles(3pm). periodt 💖✨
📦 where this page comes from
- debian bookworm: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
- debian trixie: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
- ubuntu noble: libopenoffice-oodoc-perl 2.125-4 · LGPL-2.1-only
- ubuntu questing: libopenoffice-oodoc-perl 2.125-4
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms