The Utility Library

EOEC speeds up development, but given how complicated the OpenOffice.org API is in some parts it is also very important to facilitate code reuse, and this is why we have started to collect the most often used pieces of code in a supplemental API package. This is the util module that you can access from your extensions.

util.draw

The functions in this module deal with UNO API related to Draw objects.

The unit of measurement used for coordinates in the UNO API is one thousandth of an inch. It is also used internally in OpenOffice.org and only integer coordinates are allowed.

util.draw.rgb(r, g, b)

Converts a color given in float representation to the format used in the UNO API. For example rgb(1.0, 0.0, 0.0) is red.

Parameters:

• r (float) – red component in range 0.0 - 1.0
• g (float) – green component in range 0.0 - 1.0
• b (float) – blue component in range 0.0 - 1.0

Return type:

int

Returns:

the integer representation of the color suitable for use with the UNO API

util.draw.RGB(r, g, b)

Converts a color given in integer representation to the format used in the UNO API. For example rgb(255, 0, 0) is red.

Parameters:

• r (int) – red component in range 0 - 255
• g (int) – green component in range 0 - 255
• b (int) – blue component in range 0 - 255

Return type:

int

Returns:

the integer representation of the color suitable for use with the UNO API

util.draw.setpos(shape, x, y, w=None, h=None)

Moves and optionally resizes a Draw object.

Parameters:

• shape – the shape to move
• x, y (int) – destination coordinates

util.draw.createShape(model, page, shapetype, color=None)

Creates a new shape and adds it to the DrawPage.

The shape is created by:

model.createInstance( 'com.sun.star.drawing.%sShape'%shapetype )

Parameters:

• model (com.sun.star.lang.XMultiServiceFactory) – The document object that can be used to create an instance of the given shape type. Normally it is the object you got the DrawPage from.
• page (com.sun.star.draw.DrawPage) – The page to insert the new shape into. Normally one of the DrawPages of model.
• shapetype (string) – the kind of shape to be created
• color (int or None) – the fill color or None for a transparent shape

util.draw.createPolygon(model, page, coordss, color=None, type='PolyPolygon')

Uses createShape to create a com.sun.star.drawing.PolyPolygonShape or com.sun.star.drawing.PolyLineShape. The “PolyPolygon” shape is made up of the combination of a number of polygons, each of which are a closed outline. (The polygons are implicitly closed, there is no need to duplicate the first point.) The “PolyLine” shape is a collection of line sequences.

Parameters:

• model (com.sun.star.lang.XMultiServiceFactory) – The document object that can be used to create an instance of the given shape type. Normally it is the object you got the DrawPage from.
• page (com.sun.star.draw.DrawPage) – The page to insert the new shape into. Normally one of the DrawPages of model.
• coordss (list of lists of pairs of integers) – The list of polygons each described by a list of their points which in turn are described by their integer coordinates. For example [[(0, 0), (1, 0), (1, 1), (0, 1)]] is a unit sized square.
• color (int or None) – the fill color or None for a transparent shape
• type (string) – 'PolyPolygon' (the default, for drawing closed polygons) or 'PolyLine' (for drawing open line segments).

util.draw.embed(doc, imagefilename)

Inserts the image into the document as an embedded image. As opposed to a linked image it will be saved into the document instead of becoming an external dependency.

Parameters:

• doc (com.sun.star.lang.XMultiServiceFactory) – The document object to insert into, for example a com.sun.star.text.TextDocument.
• imagefilename (string) – The name of the image file in system-specific format (not as a URL).

util.writer

The functions in this module deal with UNO API related to Writer documents.

util.writer.getWord(view)

Gets the word under the text cursor. Returns a cursor object for the word which you can then use to access and modify the word:

import util.writer
cursor = util.writer.getWord(self.getcontroller())
if cursor.String == 'something':
        # replace something with something else
        cursor.String = 'something else'

Parameter:view (com.sun.star.text.XTextViewCursorSupplier) – The current TextDocumentView typically as returned by extensioncore.ComponentBase.getcontroller(). Return type:com.sun.star.text.XTextViewCursor Returns:A cursor object for the word.

util.web

Since the web contains such a large number of useful sources of information and services, an extension might want to make efficient use of it. The goal of this module is to help with this.

util.web.loadpage(url)

Retrieves the page with the given URL.

urllib2 is used and the User-agent HTTP header is set to:

Mozilla/5.0 (OpenOffice.org extension "My Extension" created with EuroOffice Extension Creator)

The extension name is injected by the create.py script. To use a different User-agent header, util/web.py will have to be modified.

Parameter:url (string) – URL of the page to retrieve Return type:string Returns:contents of the web page

util.web.getpage(url)

Retrieves the page with the given URL.

This function uses a global cache object. If the given URL has already been retrieved by getpage(), it will be served from a persistent cache. If it has not yet been cached, it is retrieved with loadpage() and added to the cache.

Parameter:url (string) – URL of the page to retrieve Return type:string Returns:contents of the web page

util.web.flatten(x)

Flatten a Beautiful Soup object. Sometimes nothing but the bare text content is wanted from part of a web page, and this function supplements the Beautiful Soup API to provide access to it.

Parameter:x – the Beautiful Soup object Return type:string Returns:the flattened string

util.web.MAX_CACHE_SIZE

The maximal cache size. Once the cache reaches this size it is deleted and a new cache is started.

Defaults to 10MB.

util.web.setcachefile(filename)

The file name to use for the web cache. By default the file name './cache' is used, but this can depend highly on platform and OpenOffice.org build, so setting the cache file name is important.

If the file named does not exist a new file will be created. Take care, because if the file exists, but is not actually a cache file it will be overwritten with a cache file.