GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       OpenOffice::OODoc::Document - Top level component for content and
       layout processing

SYNOPSIS

               # get an ODF file handler
               my $oofile = odfContainer("myfile.odt");
               # connect a content-focused document interface
               my $content = odfDocument
                               (
                               container => $oofile,
                               part => 'content'
                               );
               # connect a style-focused document interface
               my $styles = odfDocument
                               (
                               container => $oofile,
                               part => 'styles'
                               );
               # process any content and style element
               $content->appendParagraph
                               (
                               text => "An additional paragraph",
                               style => "BlueStyle"
                               );
               $styles->createStyle
                               (
                               "BlueStyle",
                               parent => 'Text body',
                               family => 'paragraph',
                               properties =>
                                       {
                                       area            => 'text',
                                       'fo:color'      => rgb2oo('blue')
                                       }
                               );
               # commit the changes using the file handler
               $oofile->save;

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.

       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:

               my $doc = odfDocument([options]);

       This constructor, if successful, returns an object that can be used
       (according to its "member" option) to process styles, images and text.

       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).

       For example

               my $styles = odfDocument(file => "source.odt", part => "styles");

       is generally better than

               my styles = odfStyles(file => "source.odt");

       While OODoc::Document inherits all the methods and properties of these
       classes, its detailed documentation in essentially provided in the
       following manual pages:

               OpenOffice::OODoc::Text         -> text content
               OpenOffice::OODoc::Styles       -> style & layout
               OpenOffice::OODoc::Image        -> graphic objects
               OpenOffice::OODoc::XPath        -> common features & low-level API

       For example, the appendParagraph() and createStyle() methods used in
       the synopsis above are respectively described in
       OpenOffice::OODoc::Text and OpenOffice::OODoc::Styles.

       The present manual page only describes those methods (there are very
       few) which combine layout and content processing.

   Methods
       Constructor : OpenOffice::OODoc::Document->new(<parameters>)

               Short Form: odfDocument(<parameters>) or odfConnector(<parameters>)

               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".

       createImageStyle(name [, options])

               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 'properties' option is available for customizations, according
               to the OpenDocument naming rules. For example, the following
               instruction creates a style for centered images:

                   $doc->createImageStyle
                       (
                       'Centered Image',
                       properties =>
                               {
                               'style:horizontal-pos' => 'center'
                               }
                       );

       createTextStyle(name [, options])

               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.

       removePageBreak(paragraph)

               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.

       setPageBreak(paragraph [, options])

               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 => 'after'

               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's 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's style. You can do this
               with the option:

                   page => page style

               in which you give the following page's 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).

       style(object [, style])

               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's style if a style name is given as the second
               argument.

AUTHOR/COPYRIGHT

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

       Contact: jmgdoc@cpan.org

       Copyright 2004-2008 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



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.105 seconds. Last modified: November 04 2018 12:49:43.