.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "OODoc::Document 3pm" .TH OODoc::Document 3pm "2008-09-16" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" OpenOffice::OODoc::Document \- Top level component for content and layout processing .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 10 \& # get an ODF file handler \& my $oofile = odfContainer("myfile.odt"); \& # connect a content\-focused document interface \& my $content = odfDocument \& ( \& container => $oofile, \& part => \*(Aqcontent\*(Aq \& ); \& # connect a style\-focused document interface \& my $styles = odfDocument \& ( \& container => $oofile, \& part => \*(Aqstyles\*(Aq \& ); \& # process any content and style element \& $content\->appendParagraph \& ( \& text => "An additional paragraph", \& style => "BlueStyle" \& ); \& $styles\->createStyle \& ( \& "BlueStyle", \& parent => \*(AqText body\*(Aq, \& family => \*(Aqparagraph\*(Aq, \& properties => \& { \& area => \*(Aqtext\*(Aq, \& \*(Aqfo:color\*(Aq => rgb2oo(\*(Aqblue\*(Aq) \& } \& ); \& # commit the changes using the file handler \& $oofile\->save; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module defines the top level Document class, which is a connector allowing any kind of content and presentation processing. It inherits from OODoc::XPath, OODoc::Text, OODoc::Styles and OODoc::Image. .PP The most usual instruction to get access to any member of a document, with the exception if the metadata (meta.xml) should be something like: .PP .Vb 1 \& my $doc = odfDocument([options]); .Ve .PP This constructor, if successful, returns an object that can be used (according to its \*(L"member\*(R" option) to process styles, images and text. .PP This module is designed simply to create objects which include all the functionality of OODoc::Text, OODoc::Image, OODoc::Styles and OODoc::XPath (which should not be called directly by applications). .PP For example .PP .Vb 1 \& my $styles = odfDocument(file => "source.odt", part => "styles"); .Ve .PP is generally better than .PP .Vb 1 \& my styles = odfStyles(file => "source.odt"); .Ve .PP While OODoc::Document inherits all the methods and properties of these classes, its detailed documentation in essentially provided in the following manual pages: .PP .Vb 4 \& OpenOffice::OODoc::Text \-> text content \& OpenOffice::OODoc::Styles \-> style & layout \& OpenOffice::OODoc::Image \-> graphic objects \& OpenOffice::OODoc::XPath \-> common features & low\-level API .Ve .PP For example, the \fIappendParagraph()\fR and \fIcreateStyle()\fR methods used in the synopsis above are respectively described in OpenOffice::OODoc::Text and OpenOffice::OODoc::Styles. .PP The present manual page only describes those methods (there are very few) which combine layout and content processing. .SS "Methods" .IX Subsection "Methods" \fIConstructor : OpenOffice::OODoc::Document\->new()\fR .IX Subsection "Constructor : OpenOffice::OODoc::Document->new()" .PP .Vb 1 \& Short Form: odfDocument() or odfConnector() \& \& See OpenOffice::OODoc::XPath\->new (or odfXPath) \& \& Returns an OpenDocument connector, available for subsequent \& access to any element of a well\-formed document. \& \& Knowing that the Document class is a derivative of the Text, Styles, \& Image, and XPath classes, ooDocument() implicitly executes the \& corresponding constructors. So all the options of these constuctors \& are available. \& \& If no "part" parameter is given, the member selected by default is \& "content" (see OODoc::XPath). The most generally used parts are \& "content" and "styles". .Ve .PP \fIcreateImageStyle(name [, options])\fR .IX Subsection "createImageStyle(name [, options])" .PP .Vb 6 \& Creates a graphics style which is immediately usable. With no \& options, this method applies to the new style a "reasonable" set of \& characteristics which match fairly closely the default image \& presentation style in OpenOffice.org before any manual changes made \& by the user. An application can set its own options in the same way \& as createStyle in OODoc::Styles. \& \& The aim of this method is to minimise the amount of work involved in \& setting up the style, especially when the default values are close \& enough, and bearing in mind that an image must always be associated \& with a style to be displayed in a document. \& \& The code below shows a simple method of inserting an image into a \& document, in this case linked to a given paragraph (see \& createImageElement in OODoc::Image): \& \& my $anchor = $doc\->getParagraph(4); \& my $style = $doc\->createImageStyle("Photo"); \& my $image = $doc\->createImageElement \& ( \& "Eiffel Tower", \& style => "Photo", \& attachment => $anchor, \& size => "4cm, 12cm", \& import => "eiffel_tower.jpg" \& ); \& \& The \*(Aqproperties\*(Aq option is available for customizations, according \& to the OpenDocument naming rules. For example, the following \& instruction creates a style for centered images: \& \& $doc\->createImageStyle \& ( \& \*(AqCentered Image\*(Aq, \& properties => \& { \& \*(Aqstyle:horizontal\-pos\*(Aq => \*(Aqcenter\*(Aq \& } \& ); .Ve .PP \fIcreateTextStyle(name [, options])\fR .IX Subsection "createTextStyle(name [, options])" .PP .Vb 3 \& Creates a text style which is immediately usable and whose default \& characteristics are the "Standard" style in the document, even if no \& options are given. \& \& If the "Standard" style does not exist, a "reasonable" style is \& still created (this can happen in a document created from code and \& not by an interactive office software). \& \& An application can still pass all the options it wants in the same \& way as createStyle in OODoc::Styles. .Ve .PP \fIremovePageBreak(paragraph)\fR .IX Subsection "removePageBreak(paragraph)" .PP .Vb 1 \& Removes the page break from the given paragraph (before or after). \& \& This method actually removes the page break attribute from the \& corresponding paragraph style. It does not remove paragraph styles \& which may have been created to carry page breaks, so its effects are \& not technically the reverse of setPageBreak(). Generally speaking, \& however, this should not be a problem. See setPageBreak() about the \& logic of handling page breaks. .Ve .PP \fIsetPageBreak(paragraph [, options])\fR .IX Subsection "setPageBreak(paragraph [, options])" .PP .Vb 3 \& Places a page break at the position of the given paragraph. By \& default, the page break is placed before the paragraph and no \& changes are made to the page style. \& \& You can place the page break after the paragraph using the option \& \& position => \*(Aqafter\*(Aq \& \& To use this method properly every time, you must remember that a \& page break is not a text element, but a style applied before or \& after the paragraph concerned. Putting a page break in front of or \& behind a paragraph actually means adding a "page break before" or \& "page break after" attribute to the paragraph\*(Aqs style. As always, a \& page break cannot appear in the text in keeping with the principle \& of separation of content and presentation. This however adds a \& slight complication, in that all paragraphs which use the same style \& will have the page break. Otherwise, if the paragraph has a named \& style (i.e. defined in styles.xml) and we are working in the body of \& the document (i.e. in content.xml), then this method will not work \& as it cannot access both XML members at the same time. There is \& however a solution (the one used by OpenOffice.org) which consists \& simply of creating a special style for the paragraph which takes the \& old paragraph style as a parent and has only a page break attribute \& (the old paragraph style is not modified). To do this, all you need \& is the option: \& \& style => style_name \& \& This option forces the creation of an automatic style with the given \& name (make sure none other exists with the same name) and which will \& only be used to carry the page break. Later on, you can of course \& apply other characteristics to the style using the updateStyle \& method in OODoc::Styles, but this is not recommended. It is better \& not to use page break styles for other purposes. The nature of the \& existing paragraph style dictates whether or not you create a page \& break style. If the paragraph style is a named style (i.e. defined \& in styles.xml and visible to the user), you must create a page break \& style, but if it already has an automatic style you must not. The \& quite rare but most complicated scenario is where the paragraph has \& an automatic style shared by several paragraphs. In this case you \& must then make copies of the styles using the methods in \& OODoc::Styles. \& \& A page break can allow you to change a page\*(Aqs style. You can do this \& with the option: \& \& page => page style \& \& in which you give the following page\*(Aqs style (i.e. the logical name \& of a master page. See OODoc::Styles). Remember that if the "page" \& option is given, the page break is forced before the paragraph (the \& "position" option does not work in this case). .Ve .PP \fIstyle(object [, style])\fR .IX Subsection "style(object [, style])" .PP .Vb 3 \& Returns the style name of a text or graphics object. If the first \& argument is a "master page" (see OODoc::Styles), it even returns the \& associated "page layout". \& \& Replaces the object\*(Aqs style if a style name is given as the second \& argument. .Ve .SH "AUTHOR/COPYRIGHT" .IX Header "AUTHOR/COPYRIGHT" Developer/Maintainer: Jean-Marie Gouarne .PP Contact: jmgdoc@cpan.org .PP Copyright 2004\-2008 by Genicorp, S.A. .PP Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk). .PP License: \s-1GNU\s0 Lesser General Public License v2.1