Extending the UNO API

Various functionalities of the LibreOffice are available through its programming interface, the UNO API. Here I discuss how to extend it.

What is UNO API?

Many functionalities of the LibreOffice is available through UNO API. You can write extensions and external programs that use LibreOffice functionality without the need to change the LibreOffice core source code.

Extensions work seamlessly with the software, and external applications can connect to the LibreOffice process and use it. The ability to do that depends on the UNO API.

On the other hand, some functionalities may not be available through this API. For example, newer features of the decent versions of LibreOffice, or functionalities that are not useful and/or important for external applications. Sometimes, you may want to use such functionalities elsewhere. Then you have to modify the LibreOffice core source code, and expose those functionalities through the API make them available to the external applications.

Let’s refer to the LibreOffice Developer’s Guide, which is mostly around the LibreOffice UNO API. There, you can read:

“The goal of UNO (Universal Network Objects) is to provide an environment for network objects across programming language and platform boundaries. UNO objects run and communicate everywhere.”

As UNO objects should be usable across different languages and platforms, they are described in an abstract meta language called UNOIDL (UNO interface definition language). This is similar to the IDL definitions in many other technologies like CORBA.

Example UNO API: FullScreen

The API that I discuss here, provides functionality to control full screen functionality for top level windows. Stephan, experienced LibreOffice developer, added that API in this commit:

commit af5c4092052c98853b88cf886adb11b4a1532fff

Expose WorkWindow fullscreen mode via new XTopWindow3

...deriving from the existing XTopWindow2. (Exposing this functionality via UNO
is useful e.g. for some embedded LOWA example application.)

The changes in this commit are over these files:

offapi/UnoApi_offapi.mk
offapi/com/sun/star/awt/XTopWindow3.idl
toolkit/inc/awt/vclxtopwindow.hxx
toolkit/source/awt/vclxtopwindow.cxx

First one, offapi/UnoApi_offapi.mk is needed to introduce the IDL file, according to its module, in a proper location. XTopWindow3.idl is added in com/sun/star/awt, which corresponds to com.sun.star.awt module. The other two, vclxtopwindow.hxx and vclxtopwindow.cxx are the implementation of the API in C++.

Let’s look into XTopWindow3.idl:

module com { module sun { module star { module awt {

/** extends XTopWindow with additional functionality

@since LibreOffice 25.2
*/
interface XTopWindow3: XTopWindow2 {
/** controls whether the window is currently shown full screen */
    [attribute] boolean FullScreen;
};

}; }; }; };

As you may see, it contains these important information:

1. It is an interface, called XTopWindow3.

2.It has a boolean attribute, FullScreen.

3. This functionality will be available in LibreOffice 25.2 and later.

4. This interface extends XTopWindow interface. You may find the documentation for XTopWindow in api.libreoffice.org.

More information about XTopWindow interface can be found in XWindow section of the LibreOffice Developer’s Guide, chapter 2.

C++ Implementation

C++ implementation basically consists of two functions to set and get the FullScreen property:

sal_Bool VCLXTopWindow::getFullScreen() {
    SolarMutexGuard g;
    if (auto const win = VCLXContainer::GetAsDynamic()) {
        return win->IsFullScreenMode();
    }
    return false;
}

void VCLXTopWindow::setFullScreen(sal_Bool value) {
    SolarMutexGuard g;
    if (auto const win = VCLXContainer::GetAsDynamic()) {
        return win->ShowFullScreenMode(value);
    }
}

Final Words

Some APIs are much more complex. The one that was discussed here was only an example to show the required things to extend UNO API. You can browse the API documentation in api.libreoffice.org for more complex APIs:

• Reference documentation for the UNO IDL API.