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

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.

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);
try
{
    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;
    exit(1);
}

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:

• LibreOffice Developer’s Guide

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:

• LibreOffice API Examples, C++

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