Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OODoc::Image(3)	      User Contributed Perl Documentation      OODoc::Image(3)

       OpenOffice::OODoc::Image	- Image	manipulation methods

       The OpenOffice::OODoc::Image class is a derivative of
       OpenOffice::OODoc::XPath	designed for the manipulation of graphics
       objects contained in documents. It mainly allows	you to modify the size
       and position of an image	and exchange its content outside the document.

       This class should not be	explictly used in an ordinary application,
       because all its features	are available in the
       OpenOffice::OODoc::Document class, in combination with other features.
       So, each	time an	application needs to get an image-focused access to a
       document, it should use the general odfDocument() constructor instead
       of the odfImage() one.

       Practically, the	present	manual is provided to describe the image-
       container processing features of	OpenOffice::OODoc::Document (knowing
       that these features are technically supported by	the
       OpenOffice::OODoc::Image	component of the API).

       Knowing that an image is	displayed or printed according to a style, the
       OpenOffice::OODoc::Image	features should	be used	in conjunction with
       the OpenOffice::OODoc::Styles ones. The OpenOffice::OODoc::Document
       class allows the	user to	invoke text-, style- and image-focused methods
       from the	same object.

       All the methods described here can equally be used with images
       contained in style sheets (headers, footers) as with images contained
       in the body of a	document. It can therefore be associated just as well
       with a "styles.xml" member as with a "content.xml" member of an file.

       This class works	with all types of document (text, presentation,	etc.).

       For all methods where the first argument	is given below as "image", it
       is (unless otherwise stated) either the name of an image	as it appears
       to the end user when editing its	properties in or
       StarOffice or the image's element reference obtained previously by the
       program.	All these methods fail and return a null value (or in some
       cases produce an	error message) if the argument does not	correspond to
       a known image contained in the document.

       Note: This module is not	an image-processing tool. It can insert	or
       remove images, and control the way the images are displayed in the
       documents. But it can't process the images themselves.

       Constructor : OpenOffice::OODoc::Image-_new(_parameters_)

	       Short Form: odfImage(<parameters>)

	       This constructor	should not be explicitly used in ordinary applications
	       knowing that all	the features of	the returned object are	inherited by
	       any Document object.

	       See OpenOffice::OODoc::XPath->new for commun arguments.

	       The XML member loaded by	default	is 'content.xml', but only member
	       => 'styles' is required if you want to work with	page background
	       images. Example:

		       my $doc = odfImage
			       file    => 'my_presentation.odp',
			       part    => 'styles.xml'

	       Real applications should	not expressly use this constructor,
	       knowing that the	compound OpenOffice::OODoc::Document (whose
	       usual constructor is ooDocument)	inherits all the features
	       of OpenOffice::OODoc::Image.

       createImageElement(name [, options])

	       Creates an element which	represents an image and	inserts	it into	the
	       document	according to given parameters. The image element created is
	       only an anchor. It then needs to	have a graphical content loaded
	       into it and, if needed, be given	parameters using other methods.



	       inserts a default image element called "Logo".

	       Normally, the image name	is unique in an document	but
	       no checking of its uniqueness is	performed here.	Things you should
	       know, however, are:

		   - if	several	images have the	same name, one only of them can	be
		   retrieved and handled by methods which use the name to identify
		   them. It is almost impossible to know which of them it will be,
		   without a thorough knowledge	of the format and
		   the internal	logic of OODoc.
		   - if	the document is	subsequently read and saved by (which controls the uniqueness of image names),
		   sequential numbers will be given to all but one of the repeated
		   names in order to make them unique.

	       Attributes can be passed	in pairs [parameter => value]. Such as:

		       style	       => image	style name

	       It should be noted that an image	should normally	be associated with
	       a graphic style.	The presence of	a style	is not obligatory when
	       calling createImageElement (and this is not checked), but the image
	       should preferably be actually linked to an existing style before
	       displaying or printing the document. See	OpenOffice::OODoc::Styles
	       for style creation or, better, OpenOffice::OODoc::Document for image

		       attachment      => anchor element

	       indicates if the	image is attached to a text element (for ex. a
	       paragraph), and which one. This parameter must be an existing
	       element reference (obtained, for	example, using getElement or
	       selectElementxxx). It is	useless	if the image is	linked to a page.
	       The OASIS OpenDocument specification doesn't provide the	list of
	       possible	attachments for	an image, and make some
	       differences in this area	between	the different document classes.
	       For example, OOo	Writer doesn't display images which are	directly
	       attached	to table cells,	while OOo Calc does (in	text documents,
	       an image	which appears in a table cell is attached to a paragraph,
	       possibly	empty, belonging to the	cell; see the example below).

		       page	       => anchor page

	       If this parameter is used, it indicates that the	image will be
	       anchored	to a page, and the given value is a page number. It does
	       not matter if, when createImageElement is called, this number is
	       beyond the end of the document or not. If the content class of the
	       document	is "presentation" (Impress) or "drawing" (Draw), then the
	       page option is mandatory	and must be either the visible name or the
	       element reference of an existing	draw page. In a	"text" content,
	       all that	matters	is that	the particular page exists when	it is opened
	       by and if	this parameter is absent, the image is
	       anchored	to a paragraph.

		       position	       => coordinates

	       This parameter indicates	the x,y	coordinates of the image in
	       relation	to its anchor point. By	default	and generally, if the page
	       parameter is given, the origin (0,0) is the top left corner of the
	       physical	page. When attached to a text element, if there	is no given
	       position, the image is appended to the text.

	       Coordinates go from left	to right and top to bottom, however
	       everything really depends on the	image style. Coordinates should	be
	       given here in the form of a string "x,y", and the default unit is
	       centimeters. You	can choose millimeters instead by attaching the
	       usual abbreviation, such	as "12.5cm, 35mm" which	is the same as
	       "125mm, 3.5cm" or "12.5,3.5", etc. The point ("pt") unit	is allowed
	       as well.

		       size	       => size

	       The image's size	(width,	height)	is given here in the same syntax as
	       for position. Caution: if no size is given, you must not	assume that
	       the image will be spontaneously displayed in the	document in a
	       convenient size.	Remember that the "original" size of the image is
	       not automatically selected by default; the application must provide
	       a display size. If an image is to be displayed according	to its
	       original	size which is not known	in advance, you	can get	it using,
	       for example, the	imgsize() function of Image::Size (this	function
	       returns the size	in points, so the "pt" unit must be expressly
	       selected	unless you convert the size in centimeters).

		       description     => label

	       This optional parameter gives the descriptive text (long	label) for
	       the image as it will appear to the end user when	editing	the image's

		       link	       => link

	       The link	parameter contains a reference to the image's physical
	       content which can be inserted into an file (internal
	       link) or	a reference to an external file	or even	the URL	of an image
	       accessible using	a communication	protocol supported by the suite.

	       Remember	that, with, physical images are "referenced",
	       and not "loaded"	into XML elements. The reverse of course would not
	       only be against "good practice" but would result	in outrageously
	       large documents.	According to the OpenDocument specification, the
	       conforming applications could embed base-64-encoded graphics in the
	       XML elements, but this option is	not used when you insert an image
	       in a document through the OOo GUI.

	       If the target link is unavailable when the document is displayed,
	       an error	message	is displayed in	place of the image. (See imageLink
	       about links.) This parameter is useless if import is given.

	       Relative	paths in the local filesystem are allowed, but should be
	       used with care, due to differences between operating systems... and
	       between editing applications (for example, in a Unix environment,
	       OOo 2.x requires	"../image.jpg" while OOo 1.x allows "image.jpg"	for
	       a link to an image file in the current directory).

		       import	       => image	file

	       The presence of this parameter indicates	that the image content
	       should be imported from an external file	and, implicitly, that the
	       image link (which it is useless to give here) points to the image
	       imported	into the	file. The import will only be made
	       when all	the updates are	validated by a save(). See importImage()
	       about importing images. An imported image is *not* embedded in the
	       XML image element; it's always referred to through a link, and stored
	       in a separate, non-XML member of	the ODF	archive. However, with the
	       "import"	option,	the appropriate	internal link is automatically
	       created and the new member, containing the image, is automatically
	       built later, when the save() method is executed from the	current
	       document	(provided that the image file is available).

	       For those who know the appropriate XML vocabulary, there	are other
	       parameters you can pass.	Parameters other than those described above
	       are written to the image's XML element as is and	without	any checks.

	       All of these attributes,	and others, can	be read	or modified later
	       by other	methods.

	       We would	discourage you from relying on the default choices in a
	       serious application, but	it is still a possibility. With	no
	       parameters (other than mandatory	image name), the createImageElement
	       method chooses its own often arbitrary course according to the
	       following circumstances:

		   - if	the OODoc::Image object	is associated with a document body
		   (document-content) then a new paragraph is created at the end of
		   the document	and the	image is inserted into this paragraph
		   (appears at the end of the text). Repeated image creations
		   without parameters will therefore add images	one after the other
		   at the end of the document.
		   - if	the OODoc::Image object	is associated with a background
		   (document-styles) then it tries to create a paragraph in the
		   first available header and insert the image into it.	If no page
		   style contains a header, the	same is	attempted in the first
		   available footer. If	there is no footer either, the creation
		   fails with the message "No valid attachment".

	       This method otherwise tries to be "intelligent" whenever	the set	of
	       parameters is incomplete. If the	results	are useful, then the rest
	       is up to	you...

	       The method returns the new image	element's reference (undef if it

	       The following example attaches an image to a paragraph, gives it	a
	       size, loads its content into it from an external	file and attributes
	       a style to it which has been defined elsewhere. You will	note that
	       this example combines an	OODoc::Image method (createImageElement)
	       with an OODoc::Text method (getParagraph). This means that, here,
	       the $doc	object is a OODoc::Document class. See also
	       createImageStyle	in OODoc::Document.

			       description     => "Kilimanjaro in winter",
			       attachment      => $doc->getParagraph(4),
			       size	       => "5cm,	3.5cm",
			       style	       => "gr1",
			       import	       => "C:\Images\Landscape.jpg"

	       The same	image element could be inserted	in a table cell. To do
	       so, in a	spreadsheet document, the "attachment" option could be
	       set with	a $doc->getCell($table,	$row, $column) value. But the
	       present version of doesn't allow direct cell
	       attachments in text documents; the image	element	must be	attached
	       to a paragraph which is in turn attached	to the target cell. So
	       a possible approach consists of 1) issuing a setText($cell, "") in
	       order to	ensure the target cell contains	an empty text paragraph
	       and 2) provide an "attachment" option set to
	       $doc->getCellParagraph($cell) in	order to anchor	the image to this

	       Remember: creating an image element will	only make that image appear
	       in the document if 1) the image has a valid link	which points to	a
	       valid image, 2) the corresponding graphics file exists (loaded
	       possibly	using importImage) in the archive if it	is an internal
	       link, and 3) the	image has a style actually defined elsewhere
	       (either pre-existing, created using the createStyle method of
	       OODoc::Styles, copied from another document using replicateElement,
	       or coming from another source).

       exportImage(image [, destination])

	       Exports the content of an image contained in a document if the
	       OODoc::Image object was linked to a file	when it	was created (with
	       file or archive parameters passed to the	new constructor).

	       The first argument is either the	name of	the image (as it would
	       appear to the end user in the image's properties	in,
	       or the image element's reference	if the program already has it.

	       The second optional argument is the destination file. Example:

		       $doc->exportImage("Logo1", "C:\My Documents\logo.jpg");

	       It is up	to the application to choose an	appropriate extension for
	       the exported file (.jpg,	.gif, .png, etc.). You can easily find out
	       which extension using the imageLink accessor.

	       Without the second argument, the	image file is created in the
	       current directory, and its name is the name of the image	in the
	       document, with an extension depending on	the format (.jpg, .png,
	       etc), according to the information stored in the	document (but
	       the format is not checked). Be careful, the export fails	unless
	       such a construct	provides a valid file name for the operating system.
	       If the image is unnamed in the document,	exportImage() tries to
	       build a path/name which replicates the internal path/name of the
	       image in	the archive and	to use it under	the current directory
	       (this path normally begins with "Pictures/").

	       Caution:	this method only exports what is exportable i.e. internal
	       images (physically contained in the file). It has no effect if used
	       with an image inserted by an external link into the document.


	       Exports all or part of the images contained in a	document.

	       By default, and with no parameters, each	internal image is exported
	       to a file whose access path is the same as it would be if using
	       exportImage. This behaviour can be changed by parameters	passed
	       in hash form (parameter => value).

	       Possible	parameters are as follows:

		       selection       => filtering of image names (regex)
		       filter	       => filtering of image names (regex)
		       name	       => filtering of image names (regex)
		       target	       => path and/or basic filename
		       path	       => path and/or basic filename
		       suffix	       => extension to be given	to filenames
		       extension       => extension to be given	to filenames
		       start_count     => begin	count indicator

	       The "filter", "selection" or "name" parameters allow you	to export
	       only those images whose names match the given regular expression.
	       Such filtering works on the name	as the document	"knows"	it, i.e. as
	       it appears to the end user in the image's properties within the
	       document. It is not a technical filter and does not allow, for
	       example,	selection of images according to their file type.

	       The "target" or "path" parameters allow you to choose the access
	       path and	basic filename for exported files (e.g.
	       "/usr/local/images/img"). If given, a sequential	number will
	       automatically be	added to the basic filename to identify	each file.
	       The "suffix" or "extension" parameters allow the	application to
	       force a common extension	for each file instead of leaving the
	       extension as it existed in the archive (which normally identifies the
	       physical	image type).

	       By default, the sequential numbers given	to filenames (between basic
	       name and	extension) are reset to	zero each time exportImages is
	       called. An application can however force	the numbering to start at a
	       different value using the "start_count" parameter.

	       In a list context, this method returns a	list of	exported files
	       which the application can use later. In a scalar	context, it returns
	       the number of exported files.


	       Returns the list	of all image elements in the active context. If	the
	       current OODoc::Image object is associated with document-content,
	       this will be the	images contained in the	body of	the document. If
	       associated with document-styles,	this will be the images	linked to
	       headers and footers.



	       Returns the element which corresponds to	the image whose	name is
	       given as	an argument. This name is usually unique as
	       does not	allow the user to give two files the same name in a
	       document. It is the name	which appears in the "Options" tab when
	       editing the object's properties in Writer, or in the
	       "Name object" dialog box	when you right-click an	image in Impress. Returns undef if	the image is not found.

	       Can also	be used	as a check method by specifying	an element as the
	       argument	instead	of a name. In this case, the given element is
	       simply returned without modification if it is indeed an image or
	       undef if	not.

	       Caution:	images do not always have names.	Writer gives
	       default names to	images (e.g. Image1, Image2, ...) if the user does
	       not deliberately	name them. This	is not the case	in Impress.


	       This method returns the given image's link (see definition of "link"
	       in the section on imageLink), but only if it is an internal link	in
	       a form which is directly	usable by a zip	archive	management tool
	       (without	the initial "#").

       imageAttribute(image, attribute [, value])

	       Accessor	which allows you to check or modify (even create) an
	       image's XML attributes directly.	The attribute is modified or
	       created if a value is given as the third	argument. If not, it
	       returns the current value of the	attribute if found, or undef if
	       not. The	name and value of the attribute	must be	given according	to
	       the vocabulary.

	       This generic accessor remains invisible to most applications as
	       specialist accessors are	available for the most useful attributes
	       (e.g. imageLink,	imageName, etc.).

       imageDescription(image [, text])

	       Returns an image's description, or if the "text"	argument is given,
	       replaces	it. This description corresponds to the	optional text which
	       appears in the Options tab when editing the image's properties in It is not used in Impress or Draw documents.

       imageLink(image [, link])

	       Reads or	modifies an image's link. A link is the	address	of the file
	       which physically	contains the image.

	       If working with an image	loaded into the	document (often	but not
	       always the case), the link is internal and the file is physically
	       stored in the zip archive containing the	document. In this case,	the
	       link is written as "#Pictures/xxxx". It corresponds to what the user
	       would see if opening the	file using a zip archive tool instead of
	       opening it in

	       If working with an external image, the link is then the URL of the

	       The same	method allows you to read and modify the link. If a second
	       argument	is given, it cancels and replaces the existing link, or
	       creates a link if the image was still "empty".


		       $doc->imageLink("Logo", "");

	       Caution:	the actual physical existence of a valid image which
	       corresponds to the link is not checked.

       imageName(image [, name])

	       Reads an	image's	name, or if the	second argument	is given, replaces

	       Returns undef if	the first argument (name or reference) is not an

       imagePosition(image [, x, y])

	       Allows you to read or modify the	coordinates of an image	in relation
	       to its anchor point. Coordinates	are returned in	the form of a pair
	       of values.


		       my ($x, $y) = $doc->imagePosition("Landscape");

	       If the coordinate arguments are given, they replace the image's old

	       Caution:	coordinates are	not numeric values in the classic sense	of
	       the word. They are character strings starting with numeric values
	       and ending with units of	measure	(normally "cm" or "mm"). If an
	       application passes only numeric arguments without giving	a unit of
	       measure,	the default unit is assumed to be the centimetre.


		       $doc->imagePosition("Landscape",	"2.5cm", "5.125cm");

	       Normally, coordinates are measured from left to right and from top
	       to bottom starting from the point of reference. The point of
	       reference is normally the top left corner of the	page or	paragraph
	       to which	it is anchored (depending on the type of anchorage). All
	       this can	depend on the page style.

       imageSize(image [, height, width])

	       Allows you to read or modify the	display	size of	an image. Returns
	       the height and width as a pair of values. If height and width
	       arguments are provided, they replace the	image's	old size.

	       Note that this method deals with	the display size only, and ignores
	       the original size of the	image; in other	words, it doesn't change
	       anything	in the graphic object itself.

	       Caution:	it is up to the	application to maintain	the aspect ratio of
	       the image if needed.

	       See the "size" option about the createImageElement() method.

	       See imagePosition() about measure formats.

       imageStyle(image	[, style])

	       Returns the name	of the image's current style, or changes this style
	       if the second argument "style" is given.	In the second case, the
	       presence	or pertinence of the called style is not checked. This can
	       otherwise be created or imported	later.

       importImage(image, filename)

	       Loads an	image's	content	from an	external file.


		       $doc->importImage("Image1", "C:\Images\Portrait.jpg");

	       This import cancels and replaces	any previous image content, if any.

	       The first argument is either the	image's	name (as the user would	see
	       it) or the image's corresponding	element	reference. In any case,	the
	       image element must already exist, created if necessary using

	       The second argument is the full path of the image file to be
	       imported	and associated to the ODF image	object.	If this	argument is
	       omitted,	importImage() assumes that the full path of the	needed
	       resource	file is	indicated by an	external link already associated
	       with the	image object in	the document (see imageLink).

	       Obviously, the imported file should preferably be in a graphic format
	       supported by most office	software products, but this method actually
	       allows you to import anything, including	data which could not be

	       Caution:	this method does not carry out the import immediately and
	       does not	check for the presence of the file to be imported. It only
	       sends the request to the	associated OODoc::File object (via its
	       raw_import method) which	performs the operation at the next save()
	       call. As	a consequence, the image file is needed	later, but its
	       availability is not required by the importImage() method	itself.

       insertImageElement(name [, options])

	       See createImageElement.


	       Method added to OpenOffice::OODoc::Element class	objects	by the
	       OODoc::Image package and	is an element method rather than a document
	       method. Allows you to "ask" an element if it is an image.


		       print "This is an image"	if $element->isImage;


	       Deletes an image's optional image description.


	       Returns the first (or only) image (if found) which has an image
	       description matching the	provided regular expression.

	       See also	selectImageElementsByDescription().


	       Allows you to select an image element by	its link (as in	imageLink)
	       instead of by its name. The link	can be an approximation	and
	       represented in this case	by a regular expression.

	       It should only be used if you are sure that the link is unique in
	       the document. This is not normally the case, as many images can
	       share the same content. Conversely, the returned	element	is the
	       first image, in the physical XML	order, which has the given link
	       (and not	necessarily in the logical order of the	document).

	       Returns undef if	no image has the given link and	therefore allows
	       you to find out if a particular target (e.g. URL) is used in the

	       Note: if	an application needs to	get a list of individual or
	       multiple	images which share the same target, the	easiest	way is to
	       loop through the	list returned by getImageElementList() and perform an
	       imageLink() on each element.

	       See also	selectImageElementsByLink().


	       Returns a list of images	whose image descriptions match the given
	       regular expression.


	       Returns a list of images	whose internal or external links match the
	       given regular expression.

	       Allows you, for example,	to get a list of image elements	which share
	       the same	physical image file or even those which	use a particular
	       transport protocol to access these images.


		       my @webimages = $doc->selectImageElementsByLink("^http:");

	       allows you to get a list	of images referred to through an HTTP URL
	       (i.e. which will	not be visible if the user's machine is	not connected
	       to the internet).


	       Returns a list of images	whose names match the given regular

	       No variable is exported.

	       There is	a static class variable	which contains the description of a
	       default image style (in hash form):


	       This hash is not	used directly by the module itself (which offers no
	       styles functions), but it is available to any application which
	       needs to	create image styles using either XPath base methods or the
	       Styles module. Its structure is exactly the same	as the parameters
	       hash expected by	the createStyle	method.	By default, it is
	       automatically used by the createImageStyle method of the	Document

       Developer/Maintainer: Jean-Marie	Gouarne


       Copyright 2004-2009 by Genicorp,	S.A. <>

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

       License:	GNU Lesser General Public License v2.1

perl v5.24.1			  2009-01-30		       OODoc::Image(3)


Want to link to this manual page? Use this URL:

home | help