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 Microsoft Office and LibreOffice 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 (details can be found on this wiki page).
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.
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 on the following page.
Requirements
Currently there are no external requirements needed to run this UDF. You are able to work with both the Installed and also the Portable version of LibreOffice. However do take note of the methods followed to work with Portable LibreOffice?? to make sure it will fit your requirements.
Limitations
- The ability to automate LibreOffice Portable (and OpenOffice) has been added, and should work correctly. However to achieve this, it currently adds some temporary Registry entries to HKEY_CURRENT_USER, unless there is an installed version of LibreOffice or OpenOffice present. See _LO_InitializePortable for more detail.
- This UDF has been written using the English version of LibreOffice, and some aspects may only work for the English version of LibreOffice installations without errors.
- Many functions in this UDF may or may not work with OpenOffice, and some are definitely for LibreOffice only. These unfortunately have not been documented.
- For those using AutoIt versions older than 3.3.16.1 some functions in this UDF use Maps, which will not be recognized as proper syntax in older AutoIt versions.
Special Terminology
Some terminology you will encounter frequently in the UDF, and sometimes in these articles, are the following (in alphabetical order):
- Component
- Any component or module of LibreOffice. They are: Base, Calc, Draw, Impress, Math, and Writer.
- Hundredths of a MM (HMM)
- As implied by the name itself, Hundredths of a MM is a hundredth part of a Millimeter, and is the measurement unit used by LibreOffice internally for nearly all widths, heights, distances, etc. For simplicity, this is the unit type used in this UDF as well, unless otherwise stated in the Parameters. A converter function has been supplied with this UDF, found in the “LibreOffice_Helper.au3" file, called _LO_UnitConvert. This function can convert from millimeters, centimeters or inches to HMM, and back again, depending on the flag called.
- RGB color Integer
- A color unit you will find frequently in this UDF. LibreOffice nearly always uses this type of color value when setting or retrieving a color property. The RGB color integer is a number from 0 to 16,777,215, where each separate number represents a color. The relationship between RGB and a RGB Integer is based on a simple calculation: RGB Integer = Blue x (256 x 256) + Green x 256 + Red, or in Hexadecimal, 0x00RRGGBB, where RR = Red component (0-255), GG = Green component (0-255), BB = Blue component (0-255), and the highest byte (alpha) is unused and usually 0.
- UI
- User Interface, the visual windows and buttons and tabs the user sees and is used to work with LibreOffice manually.
*****************************************
Style Names
LibreOffice uses a number of Styles for various things, such as Paragraph styling, Character styling, Table and Cell styling, etc. LibreOffice automatically translates these style names according to the user's default language currently set, these are called the “Display Name”. To enable Macros, as well as LibreOffice itself to work on any language system these style names are also internally named so that they can remain constant. In the English version of LibreOffice the Display Name and the Internal name, or “Programmatic Name” of every style is most cases the same. There are a handful of exceptions to this however, for example “Default Paragraph Style” is internally named “Standard”, “No Character Style” is also internally called “Standard”, (but is classed as a Character Style, not a Paragraph Style). There are a few others as well that I won't take the time to mention as each respective style name retrieval function lists any styles that have names differing from their internal names.
In previous versions this UDF automatically converted the internal names to the appropriate display names, and vice versa using a simple find and replace list, The problem with that method however was that it also restricted the UDF more to the English language.
Initially the automatic conversion between the names was more for user convenience, as it was found that either the Display name or the Internal name would work when setting the respective styling, and seemed to make no material difference. However as of LibreOffice 25.2 a certain bug was fixed, which it was found that LibreOffice was “Accidentally” accepting both the Display Name and the Internal name, and would also occasionally cause unpredictable issues. Therefore as of 25.2 this “bug” was fixed, which means that LibreOffice's API no longer accepts both the Display Name and the Internal name, but now only accepts the Internal or Programmatic name. Therefore this UDF has been modified to do the following:
- When retrieving current setting values, any style names are left as they are found in LibreOffice's API, as the Internal style name.
- When retrieving all available style names for a particular style set, the Internal name is returned, previously the Display name was returned.
- When setting stylings, as of LibreOffice 25.2 and up the Internal style name will likely only be accepted by LibreOffice. Previous to L.O. 25.2, both styling names should be accepted, though property setting errors may be triggered as the name will be automatically converted to the internal name by LibreOffice, and will not match the called display name in some cases.
- To aid the user in recognizing what Styles are which, each respective style name retrieval function offers the ability to still retrieve the Display name, which will be returned in the same order as the Internal names are returned, allowing the user to easily have a list of each name and see which belong to which. Further than this, as stated above, each respective style name retrieval function also lists any styles that have names differing from their internal names.
Installation
Place the entire set of .au3 files of this UDF into a directory searched by SciTE (details can be found in the AutoIt help file for keyword #include).
In your script point the #Include statement to the necessary file(s).
#include "C:\Autoit Scripts\LibreOffice_Helper.au3"
No further installation or files are required.
Getting started
With the exception of working with Portable LibreOffice (see the Portable LibreOffice section regarding this), the first step will always be to acquire a Document object. In order to obtain a Document Object, the beginning step is to either open an existing file by providing the file path to the appropriate function, for example an odt or docx file would be opened with Writer, or an ods or xlsx file would be opened by Calc, etc. Alternatively you could also connect to an already opened document instance using one of the “Connect” functions. Or, finally, you may just want to create an entirely new Document using the appropriate “Create” function. The actual process on how to do this will be discussed in more detail for each element in another section.
Once a Document object is acquired, you then go forward from there to accomplish the task you desire to do. We will touch on this shortly, but first it is important to deal with the most probable question on any newcomer's mind,