UNO Data types in code and API

alsVarious data types are used in LibreOffice code and also in LibreOffice API. Here we discuss some of these data types, which are important when you are working with LibreOffice code and API.

You should know that LibreOffice API can be used from many languages, but here we only focus on C++. LibreOffice uses a component model called UNO (Universal Network Objects), which is designed to provide an environment for accessing network objects from different languages. The data types that we discuss here are among UNO data types.

UNO Data Types

The data types used in LibreOffice API are called UNO data types. They are also used extensively inside the LibreOffice code. Here we discuss the fundamental UNO data types.

Numerical/Character Data Types

First, let’s talk about simple UNO data types. If you take a look at the below table from the LibreOffice Developer’s Guide, chapter 1: First Steps you will see that it shows the numerical/character data types. When working with LibreOffice API, we do not simply use byte, short, long, int and other underlying C++ data types, but rather data types defined in LibreOffice. Those include sal_Int8, sal_Int16, sal_Int32 and their unsigned counterparts, sal_uInt8, sal_uInt16, sal_uInt32. In the past, sal_Bool was used for the boolean variables, but it is now deprecated and we simply use bool data type.

The table shows detailed information about these UNO data types, and how they are mapped into several programming languages:

Table 1: Mapping simple UNO data types to data types in different programming languages

UNO Type description Java C++ Basic
void empty type, used only as method return type and in any void void
boolean Boolean type; true and false boolean bool
(sal_Bool is deprecated)
byte signed 8-bit integer type byte sal_Int8 Integer
short signed 16-bit integer type short sal_Int16 Integer
unsigned short unsigned 16-bit integer type (deprecated) sal_uInt16
long signed 32-bit integer type int sal_Int32 Long
unsigned long unsigned 32-bit integer type (deprecated) sal_uInt32
hyper signed 64-bit integer type long sal_Int64
unsigned hyper unsigned 64-bit integer type (deprecated) sal_uInt64
float IEC 60559 single precision floating point type float float (if appropriate) Single
double IEC 60559 double precision floating point type double double (if appropriate) Double
char 16-bit Unicode character type (more precisely: UTF-16 code units)- char sal_Unicode

Character and String Data Types

Another important data type is sal_Unicode, which is used instead of char for storing Unicode character data. In C/C++, for storing strings we use OUString which can store Unicode data. As DevGuide says, LibreOffice Basic strings are mapped to UNO strings transparently. So, you don’t have to worry about converting strings to OUStrings back and forth. But in C++, you have to do the conversion from other string types yourself. We will discuss strings in a separate blog post.

UNO Description Java C++ Basic
string Unicode string type (more precisely: strings of Unicode scalar values) java.lang.­String rtl::OUString String

Enums, Structs, Sequences and Any Data Types

In C++, we use enums like ::com::sun::star::table::CellVertJustify, but because we have the shortcut css defined as com::sun::star, we can simply use ::css::table::CellVertJustify, or if we know that there will be no collision, css::table::CellVertJustify. If you add using css::table to the top of your source file, you can simply write CellVertJustify, but we don’t usually do that to avoid collision in the namespace.

One interesting data type for the LibreOffice API is the Any data type. It can be used to hold an arbitrary UNO data type. In the C++ Draw SDK example, you can see this code:

Reference xSPS(xShape, UNO_QUERY);
    xSPS->setPropertyValue("FillColor", Any(getCol(r, g, b)));
            xSPS->setPropertyValue("Shadow", Any(true));
catch (Exception e)
    std::cout << "Can not change shape colors." << std::endl << e.Message << std::endl;

This code snippet tries to change the color of a shape. Using Any(value), the color and the shadow usage of a shape is set in the XPropertySet UNO reference variable queried from xShape. If that fails, an exception handler will handle the situation.

As DevGuide describes, a Sequence is a “homogeneous collection of values of one UNO type with a variable number of elements”. In the Convertor SDK example, when trying to set the properties for a DOC -> PDF conversion, one can write this code to set the output properties needed to export a document to PDF. As you can see, 3 PropertyValues are set, each having a Name and a Value,

auto storeProps = Sequence<PropertyValue>(3);
storeProps[0].Name = "FilterName";
storeProps[0].Value <<= OUString("writer_pdf_Export");
storeProps[1].Name = "Overwrite";
storeProps[1].Value <<= true;
storeProps[2].Name = "SelectPdfVersion";
storeProps[2].Value <<= 1;
xStorable->storeToURL(sPDFUrl, storeProps);

The struct is another data type used in LibreOffice API. It can contains several elements in a record. For example, PropertyValue is a struct, defined in com/sun/star/beans/PropertyValue.hdl header file as:

struct SAL_DLLPUBLIC_RTTI PropertyValue {
    inline PropertyValue();

    inline PropertyValue(const ::rtl::OUString& Name_, const ::sal_Int32& Handle_, const ::css::uno::Any& Value_, const ::css::beans::PropertyState& State_);

    ::rtl::OUString Name;
    ::sal_Int32 Handle;
    ::css::uno::Any Value;
    ::css::beans::PropertyState State;

It is important to understand that the above header is a generated file. The UNOIDL (UNO Interface Definition Language) are used to specify UNO objects just like IDLs in CORBA or other similar technologies. The above C++ header file is generated automatically from the language independent definition IDL file udkapi/com/sun/star/beans/PropertyValue.idl defined as:

module com {  module sun {  module star {  module beans {

published struct PropertyValue
    string Name;
    long Handle;
    any Value;
    com::sun::star::beans::PropertyState State;
}; }; }; };

I will discuss IDL files in the next blog posts.

Further Reading

You can find valuable information for LibreOffice programming in the book LibreOffice Development Guide (LO DevGuide in short). Please refer to the below link to see its table of contents:

Also, the C++ section of LibreOffice examples provides a good starting point for working with LibreOffice API. It is also a starting point for understanding some parts of the LibreOffice code:

If you are building from source code, you will find C++ SDK examples in instdir/sdk/examples/cpp/ inside core source folder. Further information regarding using LibreOffice SDK examples are available in my previous blog post:

Working with LibreOffice SDK Examples