OODoc::Image(3pm)

📦
version 2.125 · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing

OpenOffice::OODoc::Image 💖

User Contributed Perl Documentation · OODoc::Image(3pm)

✨ NAME ✨

OpenOffice::OODoc::Image — Image manipulation methods 🎀

🦋 DESCRIPTION 🦋

okay bestie, listen. OpenOffice::OODoc::Image is a class that's a derivative of OpenOffice::OODoc::XPath, and it exists for one reason and one reason only: manipulating graphics objects inside documents. It mainly lets you change the size and the position of an image, and swap out its content from outside the document. That's the whole vibe. 💅

Real talk though: you should not use this class explicitly in an ordinary application, because literally every feature it has is available through the OpenOffice::OODoc::Document class, combined with other features. So every time your app needs image-focused access to a document, use the general odfDocument() constructor instead of the odfImage() one. Periodt.

Practically speaking, this manual is here 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. 🫶

And here's the thing: an image is displayed or printed according to a style, so the OpenOffice::OODoc::Image features should be used in conjunction with the OpenOffice::OODoc::Styles ones. The OpenOffice::OODoc::Document class lets you invoke text-, style- and image-focused methods all from the same object. main character energy, honestly. 👑

All the methods described here work equally well with images contained in style sheets (headers, footers) as with images contained in the body of a document. So it can be associated just as well with a "styles.xml" member as with a "content.xml" member of an OpenOffice.org 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 OpenOffice.org 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 doesn't 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. Not its job, never was, never will be. 🙈

🧚 Methods

🌸 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. iykyk.

See OpenOffice::OODoc::XPath->new for the common 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. So like, it's the skeleton, not the whole fit. 🎀

Example:

$doc->createImageElement("Logo");

inserts a default image element called "Logo".

Normally, the image name is unique in an OpenOffice.org 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 OpenOffice.org format and the internal logic of OODoc.
  • if the document is subsequently read and saved by OpenOffice.org (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 styles. 💅

  • 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 OpenOffice.org 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 OpenOffice.org 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 properties.

  • link => link

The link parameter contains a reference to the image's physical content which can be inserted into an OpenOffice.org 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 OpenOffice.org suite.

Remember that, with OpenOffice.org, 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

okay so quick lil recap before we keep going: that parameter being there at all = "hey, pull this image in from an outside file." And it implicitly means the image link (which, bestie, it's genuinely useless to pass here) points at the image that got imported into the OpenOffice.org file. The import itself doesn't happen right away — it waits until every update gets validated by a save(). Wanna know the deets on importing? Go peek at importImage(). 🫶

And listen: an imported image is not embedded in the XML image element. Not ever. It's always referred to through a link, and it lives in a separate, non-XML member of the ODF archive. But — and this is the cute part — with the "import" option, the right internal link gets created automatically, and that new member holding the image gets built automatically later, when the save() method runs from the current document (as long as the image file is actually available). ✨

For the girlies who know their XML vocabulary: there are other parameters you can pass. Anything that isn't one of the ones described above gets written to the image's XML element as-is, with zero checks. 💀

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

ngl, we'd discourage you from relying on the default choices in a serious application — but it's still a possibility, so. With no parameters at all (other than the mandatory image name), createImageElement just picks its own often-arbitrary course based on these 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 gets inserted into that paragraph (so it 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, it attempts the same thing in the first available footer. If there's no footer either, the creation fails with the message "No valid attachment". 😭

Otherwise, this method 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 fails).

Okay this example is iconic so look closely. It 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 that was defined elsewhere. And notice: this example mixes an OODoc::Image method (createImageElement) with an OODoc::Text method (getParagraph). Which means that here, the $doc object is a OODoc::Document class. Also check out createImageStyle in OODoc::Document. 💅

$doc->createImageElement
    (
    "Landscape",
    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 into a table cell. To do that, in a spreadsheet document, the "attachment" option could be set with a $doc->getCell($table, $row, $column) value. BUT the present version of OpenOffice.org doesn't allow direct cell attachments in text documents — the image element has to be attached to a paragraph which is in turn attached to the target cell. So a possible approach is: 1) issue a setText($cell, "") so the target cell definitely contains an empty text paragraph, and 2) provide an "attachment" option set to $doc->getCellParagraph($cell) to anchor the image to that paragraph. 🌸

Remember bestie: creating an image element will only make that image show up 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's 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 (so: 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 OpenOffice.org), 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's up to the application to pick 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 gets 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 heads up, 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 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. 💀

✨ exportImages([options]) ✨

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

By default, with no parameters, each internal image is exported to a file whose access path is the same as it would be if you used 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 let you export only those images whose names match the given regular expression. That 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 let you choose the access path and basic filename for the 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 let the application 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.

🌸 getImageElementList() 🌸

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 it's associated with document-styles, this will be the images linked to headers and footers. 🎀

🦋 getImageElement(image) 🦋

🦋 getImageElement(element) 🦋

Returns the element which corresponds to the image whose name is given as an argument. This name is usually unique since OpenOffice.org doesn't let the user give two files the same name in a document. It's the name that appears in the "Options" tab when you're editing the object's properties in OpenOffice.org Writer, or in the "Name object" dialog box when you right-click an image in OpenOffice.org Impress. Returns undef if the image isn't found. 😭

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

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

💜 getInternalImagePath(image) 💜

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

👑 imageAttribute(image, attribute [, value]) 👑

okay so this accessor is the generic one — it lets you check or modify (or even create, bestie, we're manifesting ✨) an image's XML attributes directly. Hand it a value as the third argument and the attribute gets modified or created, just like that. Don't hand it one, and it gives you back the attribute's current value if it finds it, or undef if it doesn't. Heads up though: the attribute's name and its value both have to be given according to the OpenOffice.org vocabulary. No inventing your own words, iykyk. 💅

And the reason most applications never even clock this one? It stays invisible to them, because specialist accessors exist for all the genuinely useful attributes (things like imageLink, imageName, etc.). So yeah — it's the understudy. Still iconic though. 🎀

💖 imageDescription(image [, text]) 💖

Gives you an image's description back, or — if you pass the text argument — swaps it out for the new one. This description is the optional text that shows up in the Options tab when you're editing the image's properties in OpenOffice.org. Not used in Impress or Draw documents, just so you know. 🙈

Reads or modifies an image's link. And what is a link, you ask? It's the address of the file that physically contains the image. Simple as that.

So if you're working with an image that's loaded into the document (which is often, but not always, the case), the link is internal, and the file is physically stored in the zip archive that contains the document. In that situation the link is written as "#Pictures/xxxx" — which is exactly what a user would see if they opened the file with a zip archive tool instead of opening it in OpenOffice.org. 🦋

If you're working with an external image, then the link is just the URL of the image. Periodt.

Same method does both jobs, btw — read and modify. Give it a second argument and it cancels and replaces the existing link, or creates a link if the image was still "empty". ✨

Example, because obviously:

$doc->imageLink("Logo", "http://www.mysite.com/logo.png");
⚠️ Caution: whether a valid image actually physically exists at that link? Not checked. The method does not care. Do not come for it.

🏷️ imageName(image [, name]) 🏷️

Reads an image's name — or, if you pass that second argument, replaces it. That's the whole vibe.

Returns undef if the first argument (name or reference) isn't an image at all. 😭

📍 imagePosition(image [, x, y]) 📍

Lets you read or modify the coordinates of an image relative to its anchor point. Coordinates come back as a pair of values. Cute, right?

Example:

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

If you do pass the coordinate arguments, they replace the image's old coordinates. Slay.

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

Example:

$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. That point of reference is normally the top left corner of the page or paragraph the image is anchored to (depending on the type of anchorage). And all of this can depend on the page style. So many layers, honestly. 💀

📐 imageSize(image [, height, width]) 📐

Lets you read or modify the display size of an image. It returns the height and width as a pair of values. Pass height and width arguments and they replace the image's old size.

Note that this method deals with the display size only — it ignores the original size of the image. In other words, it doesn't change anything in the graphic object itself. 🙅‍♀️

⚠️ Caution: maintaining the aspect ratio of the image, if that's needed, is up to the application. Not us. Never us.

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 that style if you hand over the second argument, style. And in that second case? The presence or pertinence of the style you're calling is not checked. It can be created or imported later instead. No stress, it's giving "we'll figure it out." 💅

📥 importImage(image, filename) 📥

Loads an image's content from an external file. Let's go. 🔥

Example:

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

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

The first argument is either the image's name (the one the user would see) or the image's corresponding element reference. Either way, the image element must already exist — created if necessary using insertImageElement().

The second argument is the full path of the image file to be imported and associated to the ODF image object. If you omit that argument, importImage() assumes 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 file you import should preferably be in a graphic format supported by most office software products — but honestly, this method actually lets you import anything, including data that couldn't be displayed. Chaos permitted. 🌈

⚠️ Caution: this method does not carry out the import immediately, and it 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. Short and sweet, we love a redirect. 🎀

🖼️ isImage 🖼️

This one is a method added to OpenOffice::OODoc::Element class objects by the OODoc::Image package — so it's an element method rather than a document method. It lets you literally just "ask" an element if it's an image. Main character energy, honestly. 👑

Example:

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

🗑️ removeImageDescription(image) 🗑️

Deletes an image's optional image description. Gone. Poof. ✨

🔍 selectImageElementByDescription(expression) 🔍

Returns the first (or only) image — if one is found — whose image description matches the regular expression you provided. Yep, regex.

See also selectImageElementsByDescription().

Lets you select an image element by its link (same link as in imageLink) instead of by its name. And the link can be an approximation, in which case it's represented by a regular expression.

⚠️ It should only be used if you're sure the link is unique in the document. That is not normally the case, because many images can share the same content.

Conversely, the element you get back is the first image, in the physical XML order, that has the given link — and not necessarily in the logical order of the document. Keep that in mind bestie.

Returns undef if no image has the given link, which means it also lets you find out whether a particular target (e.g. a URL) is used in the document at all. Detective vibes. 🔎

Note: if an application needs a list of individual or multiple images that 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().

📝 selectImageElementsByDescription(expression) 📝

Returns a list of images whose image descriptions match the given regular expression. Simple, useful, iconic.

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

This lets you, for example, get a list of image elements that share the same physical image file — or even those that use a particular transport protocol to access those images. 🦋

Example:

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

...which gets you a list of images referred to through an HTTP URL (i.e. the ones that won't be visible if the user's machine isn't connected to the internet). 😭

🏷️ selectImageElementsByName(expression) 🏷️

Returns a list of images whose names match the given regular expression. That's it, that's the method. 💖

💫 Properties 💫

No variable is exported. (Breathe, it's fine.)

There is a static class variable holding the description of a default image style, in hash form:

%OpenOffice::OODoc::Image::DEFAULT_IMAGE_STYLE

This hash isn't used directly by the module itself (which offers no styles functions), but it's available to any application that 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. And by default, it's automatically used by the createImageStyle method of the Document module. Chef's kiss. 👑

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

and that's a wrap on OODoc::Image, bestie!! 🫶 this whole thing ships with perl v5.34.0, dated 2022-06-16, and the page itself is OODoc::Image(3pm). go forth and image-element responsibly. 💅✨🌸

📦 where this page comes from