Libreoffice-WIP

This page is still a work in progress.

This article uses material from the Wikipedia article "LibreOffice" and other Wikipedia articles, which are released under the Creative Commons Attribution-Share-Alike License 4.0.

Introduction

This UDF (AU3LibreOffice) aids the user in creating and manipulating LibreOffice Documents.
This wiki article tries to explain basic principles of the UDF and offers tips on how to get started with automating LibreOffice (LO for brevity). It also points out some differences between automating the MS Office and LO suites.
It is not intended to explain LO's API.
To work with this UDF, you should be familiar with both AutoIt and LO.

What is LibreOffice?

LibreOffice is a free and open-source office productivity software suite developed by The Document Foundation (TDF).
It was created in 2010 as a fork of OpenOffice.org, itself a successor to StarOffice.
The suite includes applications for

• word processing (Writer),
• spreadsheets (Calc),
• presentations (Impress),
• vector graphics (Draw),
• database management (Base), and
• formula editing (Math).
  

It supports the OpenDocument format and is compatible with other major formats, including those used by Microsoft Office.
Generally speaking, OpenOffice and LibreOffice have the same foundational features, but given the fact that LibreOffice is more actively developed, LibreOffice has more, and newer features available.

Feature comparison: LibreOffice vs Microsoft Office

This page compares the features of LibreOffice and Microsoft Office in several form factors.
The comparisons separate major and minor feature differences and also includes notes on LibreOffice extensions.
The comparison highlights differences and therefore does not display any features which are present in both office suites.

LibreOffice UDF

Since LibreOffice is a fork of OpenOffice, this UDF also works with OpenOffice in many places. However, you should not rely on this, as this UDF was developed with a focus on LibreOffice.
All functions for which a minimum version of LibreOffice is specified are most likely NOT compatible with OpenOffice.

LibreOffice Object Model

The LibreOffice UDF is a wrapper for the complex LibreOffice object model. It hides the complexity of the object model and replaces it with a few AutoIt function calls.
The functions provided by the UDF cover most of the functionality that is typically required.
However, if you need more complex functions, you will have to write them yourself. First, you need to familiarize yourself with the LibreOffice API.
The following books will be a valuable help also in this line.

• OpenOffice.org Macros Explained — OOME Fourth Edition
• Useful Macro Information For OpenOffice.org

Technical comparison: LibreOffice vs Microsoft Office

For those users familiar with Microsoft Office and its automation API, we have included some comparisons between the two suites' APIs and internal behaviour.

Applications vs ServiceManager

In Microsoft Office, you always begin with a Microsoft Word, Excel or Powerpoint Application object, which is an instance of the respective component without a Document, Book, or presentation opened in it yet. The application instance is then used to create, connect or open Documents, Books or Presentations, or to set global settings. The Application instance when created can be either visible or invisible.

In LibreOffice you always begin with what is called a “ServiceManager”, this is essentially the equivalent of the Word, Excel or Powerpoint application Object, and is used to open, create or connect to Documents, Sheets or Presentations as needed.
The ServiceManager, when created, has no visible UI.

The UDFs included with AutoIt for MS Word and MS Excel include separate functions for creating an instance of the corresponding Application Object, _Word_Create and _Excel_Open, because the Application objects are unique for each component, e.g., an Excel Application is used solely for working with Excel files and settings, etc.

In the LibreOffice UDF, the user is saved steps of initializing the ServiceManager, as the ServiceManager is used alike for all the different components of LibreOffice (Base, Calc, Writer, etc.). The ServiceManager is “aware” of all opened Documents in the several LibreOffice Components, and can create instances of any component type, as needed.
It can also open any appropriate Document in the correct component as needed. When the user calls for the first time *_DocCreate, or *_DocConnect, or *_DocOpen, or any similar functions, the ServiceManager is initialized in the background, and stored as a static variable for use in the UDF when needed.

Selections and Cursors

Word vs Writer

MsOffice Word uses two types of data selections, the first is called a “Selection”, which is the visible selection you create in the Word application using your keyboard or mouse (Or also using the API). The second type is called a “Range”, and is an invisible or background selection of data, created solely using the API. Both support similar methods for extending or collapsing the selection, and have similar properties. A Range is able to be extended, or the beginning and ending position is able to be moved nearly the same as a Selection is, except a Range cannot be extended or moved by visual or on-screen lines, only structural units (paragraphs, sentences, etc.). There can be only one instance of a Selection at once, but you can have multiple Ranges at one time.
In LibreOffice Writer you also have two primary types of data selections. The first type of selection or “cursor” as it is generally known, is internally known as a “ViewCursor”, which is visible to the user. The second type of selection or “cursor” is called a TextCursor, and is invisible to the user. A ViewCursor is what you see when you select some data in the document, and is also located wherever the caret is placed in the document. A ViewCursor is “aware” of characters, lines (where you see a line breaks to go to the next line to fit the Document width), pages and screens (Your current view), as well as the start and end of the Document, it is "View dependent" for its usefulness. There can only be one ViewCursor existing in a document at one time. A ViewCursor can be used very similarly to a TextCursor for the purpose of inserting or retrieve text, inserting shapes or tables etc., as well as getting and setting properties.
The TextCursor on the other hand is always invisible to the user whether or not data is selected. The Text Cursor is “blind” to lines, pages and screens. A TextCursor can, like a ViewCursor “see” characters, but it is also aware of the start and ending of words, sentences and paragraphs, it is more "document dependent" for its usefulness. Unlike a ViewCursor, you can have as many TextCursors as needed in one document.
There is a third type of Cursor that I will mention here briefly, it is called a Table Cursor. It is, as you may have guessed, only used for manipulating Tables, whether for joining cells, coloring, or sizing rows and columns etc. A Table Cursor is only aware of the Table and its cells. It cannot transverse outside of the Table. It is aware of cells, and the beginning and ending of the Table. It can go be moved to a specific cell by name, and merge and split cells. It cannot insert or retrieve text, nor edit text attributes.
When retrieving the current selection(s) made by the user, i.e. a selected string of text, the resulting object is essentially identical to a TextCursor, and in this UDF a TextCursor is created matching the selection to be returned to lessen the number of cursor types to account for in other functions. If the selection is not just text, another type of Object will be returned, as described in the selection function.

Excel vs Calc

In Microsoft Excel there exists two types of data selections. There is a Selection, which represents what the user has currently selected with the cursor, be it a single cell or a range of cells. Secondly, there are what is known as Ranges, a Range is a group of cells, such as A2 to C4, or even a single cell. Excel treats these two very similarly, a selection is essentially the same as a Range, but is visually selected.
Similarly, in LibreOffice there are two types of data selections. There are selections, which is what ever the user has selected with the cursor, this can be text within a cell, a single cell, a range of cells (e.g. A1 to B3) or several ranges of cells (e.g. A1:C3 and D3:F5). The second type is also called a Range, this can be either a single cell, a group of cells, or even the entire sheet is considered a Range.

Newlines

Another difference it would be good to briefly touch upon, is the different line endings used between MS Office and LibreOffice. Microsoft Office, of course, uses the standard Windows CRLF (Carriage Return, Line Feed) hard newline sequence (when you push Enter while editing a document). And a LF (LineFeed) for a soft newline (when you push Shift+Enter in a document).
LibreOffice on the other hand uses the Unix style newline sequences, either CR (Carriage Return) or LF (Line Feed). The CR sequence is used for hard newlines, and the LF sequence is used for soft newlines. This generally won't be encountered nor cause much issue for the majority of tasks while automating LibreOffice. However it may become an issue when getting or inserting strings, particularly in Writer. For example, if I select several paragraphs and retrieve the text of those paragraphs for processing in AutoIt, and then replace those selected paragraphs with the text I processed in AutoIt, the resulting text will most likely not have the same amount of newlines, there would be a mixture of hard and soft newlines in the paragraph, where before there maybe was only hard newlines. The root cause for this seems to be due to the way strings are handled when retrieving them from LibreOffice, newlines use the platform default newline sequence when retrieving the string, instead of maintaining the current newline sequence used by LibreOffice, so when working on Windows, the CRLF is used for all hard newlines. This is generally only true of inserting and retrieving strings directly in the document, or any frames, textboxes, pr table cells in Writer. Caution should be exercised when inserting a string, to manually use the CR or LF sequences as needed when wanting to insert a hard or soft newline respectively.
Presently this UDF attempts to perform a find and replace operation for CRLF newlines to convert them to CR whenever strings are being set that allow newlines, and that may be affected by this issue. It is still recommended that the user does this themselves to ensure they obtain expected results. Calc does not seem to be affected by this issue, as it appears to convert any CR or CRLF to LF.

Formatting

One more less important difference between MSOffice and LibreOffice is formatting. When formatting text in MS Office, usually the user uses what is called “Direct Formatting”, i.e., selecting some text and selecting Bold, to bolden the text, or italic, etc. Not that you can't and don't create and apply formatting styles, but primarily this is how MS Office intends the user to apply formatting and styling.
In LibreOffice however, the way the user applies formatting is intended to be slightly different. This is not to say that the user cannot use “direct formatting”, they can, and many do, but it sometimes does not produce desirable results when attempts are made later on to change this or that styling, often unsightly text ends up being produced, perhaps wrong text sizing when the font was made bigger, or words still in an old font style etc.
The way LibreOffice intends the user to apply formatting and styling is by the use of what is called Paragraph Styles and Character styles. Paragraph styles, of course, would be used to apply, for example, a certain font to an entire paragraph, they modify and apply their affects to the whole paragraph where they are applied, except when overridden by direct formatting. Character styles on the other hand, as their name implies, apply the styling only to the character(s) it is applied to, generally this is used to apply coloring, bold, underlining or italic to characters as needed, except where direct formatting is applied already.
Given the fact that LibreOffice also supports direct formatting as MS Office does, this difference isn't necessarily important. But for the best experience, both manually working with LibreOffice, and while automating it with this UDF, it is recommended to use the styling approach instead, or at least keep these facts in mind to you know what to expect.

Limitations

• The UDF works ONLY for the installed version of LibreOffice, not the portable version.
• The UDF is written using the English version of LibreOffice, and may only work for the English version of LibreOffice installations.
• Many functions in this UDF may or may not work with OpenOffice, however some settings are definitely for LibreOffice only.
• For those using older AutoIt versions, several functions use Maps. In older AutoIt installations, a syntax error will be reported due to this.

References

• LibreOffice Developer's Guide: Glossary
• LibreOffice 24.2 SDK API Reference