Notebookbar, or tabbed interface is an attempt to modernize LibreOffice user interface. In these series, I try to explain the implementation in LibreOffice code. In the first part, I discuss custom Glade widgets that are building blocks of Notebookbar user interface.

Building LibreOffice From Sources

If you haven’t built LibreOffice from sources before, you can refer to can refer to this tutorial:

Getting Started (Video Tutorial)

The next sections assume that you have a working build environment.

Custom Widgets in Glade Catalogs

Notebookbar implementation consists of .ui files, configuration files and C++ implementation. Let’s look into the user interface files.

First time that you clone LibreOffice source code, and try to open a Notebookbar UI file like this, you may see error:

$ glade ./sc/uiconfig/scalc/ui/notebookbar.ui

You may see an error, which indicates that a required catalog related to LibreOffice is not available.

Glade error

To fix this issue, you have to know that Notebookbar uses custom widgets that with the Glade interface designer. These custom widgets are available from a Glade catalog with the name of LibreOffice.

Inside sc/uiconfig/scalc/ui/notebookbar.ui, you may see these two lines:

<requires lib="gtk+" version="3.20"/>
<requires lib="LibreOffice" version="1.0"/>

Glade catalogs are xml files with the keyword glade-catalog inside them, so we can search for this keyword:

$ git grep -l glade-catalog
extras/source/glade/libreoffice-catalog.xml.in
extras/source/glade/makewidgetgroup.xslt

The .in files is an input file in which the build process creates the final xml file out of it. Searching for glade-catalog inside the build folder results:

$ grep -lr glade-catalog
...
instdir/share/glade/libreoffice-catalog.xml

As you can see, the result goes inside the folder instdir/share/glade/, so to be able to use the catalog, you should add this folder to the glade catalog search path. One of the easiest ways to do this, is to add it via Glade interface itself. Use ☰ (hamburger menu), go to “Glade Preferences”, and add instdir/share/glade/ to the “Extra Catalog & Template paths”. Then, reload a notebookbar UI file, and the error should go away. This setting is saved inside ~/.config/glade.conf configuration file.

Custom Widgets for the Notebookbar

Inside the Glade custom catalog instdir/share/glade/libreoffice-catalog.xml, you can see 10 custom widgets:

$ grep "glade-widget-class\ " instdir/share/glade/libreoffice-catalog.xml
<glade-widget-class title="Notebookbar ToolBox" name="sfxlo-NotebookbarToolBox" generic-name="Notebookbar ToolBox" parent="GtkToolbar" icon-name="widget-gtk-toolbar">
<glade-widget-class title="Notebook switching tabs depending on context" name="sfxlo-NotebookbarTabControl" generic-name="NotebookbarTabControl" parent="GtkNotebook" icon-name="widget-gtk-notebook"/>
<glade-widget-class title="Horizontal box hiding children depending on its priorities" name="sfxlo-PriorityHBox" generic-name="PriorityHBox" parent="GtkBox" icon-name="widget-gtk-box"/>
<glade-widget-class title="Horizontal box hiding children depending on its priorities" name="sfxlo-PriorityMergedHBox" generic-name="PriorityMergedHBox" parent="GtkBox" icon-name="widget-gtk-box"/>
<glade-widget-class title="Box which can move own content to the popup" name="sfxlo-DropdownBox" generic-name="DropdownBox" parent="GtkBox" icon-name="widget-gtk-box"/>
<glade-widget-class title="Box which can hide own content" name="VclOptionalBox" generic-name="VclOptionalBox" parent="GtkBox" icon-name="widget-gtk-box"/>
<glade-widget-class title="Vertical box hiding children depending …

In previous blog posts about crashes in LibreOffice, I have discussed how to debug and fix some of crashes. Now I discuss a nice tool to keep track of the crash reports from volunteers: Crash report tool.

Crash Report Statistics

Crash report is available via this LibreOffice website:

• https://crashreport.libreoffice.org/stats/

You can see that different versions of LibreOffice listed there, and for each and every tracked version, number of crashes during the previous 1, 3, 7, 14 and 28 days can be seen. This is possible using the appropriate buttons on the top.

This data is gathered from those to volunteer to submit reports to make LibreOffice better.

This statistic is very helpful to understand the robustness of the builds in different versions.

Crash Signatures

If you choose a specific version, you may see signatures of the crashes. This is helpful when trying to fix crashes. For example, this is one of the crash signatures found in LibreOffice 24.8.0.3:

• SwTextINetFormat::GetCharFormat()

This shows that the crash happens in GetCharFormat() function. One may use this information to track and fix the problem.

Looking into one of the crashes, one may see the details of the crash, including the stack trace in the crashing thread, and link to the exact place of the source code that leads to the crash.

As an example, you can see this crash report.

Sometimes, experienced developers may be able to reproduce the bug using crash signatures while knowing some background. Otherwise, in most cases, filing a bug with documents and instructions to reproduce the bug is essential. Adding a link to the crash report can be helpful.

Windows Subsystem for Linux (WSL) is a mechanism to use complete Linux distributions on Windows. Here I discuss how to use it to build LibreOffice for both Linux and Windows binaries.

What is WSL?

WSL is the relatively new mechanism in Windows that lets you use a complete Linux distribution alongside your Windows. Interoperability between WSL and Windows lets you to share files and utilities between Windows and Linux. That is where it becomes helpful for LibreOffice, as LibreOffice make depends heavily on GNU tools, which are available in Linux.

Linux or Windows?

You can use WSL for 2 different scenarios:

1. Building for Linux: this is the full Linux build, in which Linux compilers, libraries and utilities will be used to create a Linux binary. You can then run or package the Linux build. You can find more information here:

• TDF Wiki – BuildingOnWSL

Using WSL2 is recommended, as it is supposed to be faster, and also you can simply use the graphical interface of LibreOffice.

LibreOffice build on WSL with Linux binaries, displayed on Windows

When you run the resulting binary, the graphical interface is usable, and it will use GTK fronted by default.

2. Building for Windows: this is the WSL as helper mode, where it uses only a few Linux utilities like pkg-config, make, automake and a few other utilities to configure the project.  Then, GNU Make for Windows will be the tool to build the project. More information is available here:

• TDF Wiki: BuildingOnWSLWindows

The results are Windows .exe files, and you can simply run them on Windows as native programs.

Build Options on Windows

You can build LibreOffice on different platforms. On Windows, it is possible to use Cygwin, but using WSL can be faster, and considering some issues with recent Cygwin versions, WSL is an alternative.

One can imagine of other ways to build LibreOffice on Windows, including MinGW. But, at the moment, MinGW, both as a helper to use Visual Studio, and also as an independent distribution to build LibreOffice, is not usable due to various reasons.

And last note: if you do not have prior experience with LibreOffice development but you are interested, you can start from our video tutorial for getting started with LibreOffice development.

LibreOffice options page provides rich set of settings for everyone who wants to tune LibreOffice to match their needs. But, what if you as a developer, need setting dialogs that are needed elsewhere in the LibreOffice application? Here I discuss some of such use cases, which are handled by defining UNO commands.

Options Page

The code for providing “Tools > Options” is not in a single module, but main part resides in cui module, which contains code which is used across different modules. Looking into cui/source/options/ folder from LibreOffice core source code, you can see various different source files related to the options. The biggest file there is cui/source/options/treeopt.cxx, which is the actual implementation of the tree-based dialog that you see when you open Tools > Options dialog. There are other C++ files that handle .ui files related to options. You can find those UI files in cui/uiconfig/ui/ folder with a name like opt*.ui:

$ ls cui/uiconfig/ui/opt*.ui

These files can be edited and they are used as described in the LibreOffice design blog:

• LibreOffice Design Blog: Easyhacking: How to create a new “Tip-Of-The-Day” dialog

UNO Dispatch Commands

Only some of the dialogs can be opened available via UNO dispatch commands. As an example, you may see “.uno:AdditionsDialog” is used both in cui/source/options/optgdlg.cxx for creating a dialog in Tools > Options (when you click for “more icons”), and also in sfx2/source/appl/appserv.cxx.

You can try running this UNO command in LibreOffice BASIC editor with this code snippet:

Sub Main()
    Set oDispatch = CreateUnoService("com.sun.star.frame.DispatchHelper")
    Dim args(0) As New com.sun.star.beans.PropertyValue
    Set oFrame = StarDesktop.Frames.getByIndex(0)
    oDispatch.executeDispatch(oFrame, ".uno:AdditionsDialog", "", 0, args)
End Sub

The above command is defined specifically to help developers use the “Extensions” dialog, anywhere in LibreOffice UI, from top menus to context menus and toolbars and also in code, in a simple way.

There is another dialog titled “Security Options and Warnings”, which is opened through .uno:OptionsSecurityDialog UNO command. In this way, it can be used easily in other modules of LibreOffice.

SecurityOptionsDialog

Implementing UNO Command

Adding a new UNO command was discussed before, in a separate blog post:

Adding a new UNO command

Adding a new UNO command for an options dialog is basically the same. There can be differences regarding the configurations and the data that is passed between the dialog and the caller.

When you create a dialog box directly like the code snippet below, you have access to the member functions defined for that specific dialog:

IMPL_LINK_NOARG( SwGlossaryDlg, PathHdl, weld::Button&, void )
{
    SvxAbstractDialogFactory* pFact = SvxAbstractDialogFactory::Create();
    ScopedVclPtr<AbstractSvxMultiPathDialog> pDlg(pFact->CreateSvxPathSelectDialog(m_xDialog.get()));
    SvtPathOptions aPathOpt;
    const OUString sGlosPath( aPathOpt.GetAutoTextPath() );
    pDlg->SetPath(sGlosPath);
    if(RET_OK == pDlg->Execute())
    {
        const OUString sTmp(pDlg->GetPath());
        if(sTmp != sGlosPath)
        {
            aPathOpt.SetAutoTextPath( sTmp );
            ::GetGlossaries()->UpdateGlosPath( true );
            Init();
        }
    }
}

As you can see, pDlg->GetPath() is accessible here, and you can use it to …

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 …

Here I discuss what fuzz testing is, and how LibreOffice developers use it incrementally to maintain LibreOffice code quality.

Maintaining Code Quality

LibreOffice developers use various different methods and tools to maintain LibreOffice code quality. These are some of them:

1. Code review: Every patch from contributors should pass code review on Gerrit, and after conforming to coding standards and conventions, it can become part of the LibreOffice source code.

2. Static code checking: “Coverity Scan” continuously scans LibreOffice source code to find the possible defects. An automated script reports these issues to the LibreOffice developers mailing list so that developers can fix them.

3. Continuous Testing: There are various C++ unit test and Python UI tests in LibreOffice core source code to make sure that the functionalities of the software remain working during the later changes. They are also helpful for making sure that the fixed regressions do not happen again. These test run continuously for each and every Gerrit submission on CI machines via Jenkins.

4. Crash testing: A good way to make sure that LibreOffice works fine is to batch open and convert a huge set of documents. This task is done regularly, and if some failure occurs developers are informed to fix the issue.

5. Crash reporting: LibreOffice uses crash testing to find out about the recurrent crashes, and fix them.

6. Tinderbox Platforms: Using dedicated machines with various different architectures, LibreOffice developers make sure that LibreOffice source code builds and runs without problem on different platforms. Here is the description of tinderbox (TB) from TDF Wiki:

Tinderbox is a script to run un-attended build on multiple repos, for multiple branches and for gerrit patch review system.

LibreOffice tinderboxes status

You can see the build status here:

https://tinderbox.libreoffice.org/

7. Fuzz testing: LibreOffice software is checked continuously using Fuzz testing. This is essentially giving various automated inputs to the program to find the possible places in the code where problem occurs. Then, developers will become aware of the those problematic places in the code, and can fix them.

Fuzz Testing LibreOffice

Fuzz testing on LibreOffice source code is active since 2017, and since then there has been various bug fixes for the problems that the fuzz tester reported. You can see more than 1500 of such fixes in the git log until now:

$ git shortlog -s -n --grep=ofz#

Issues Found with Fuzz Testing

This tool can find various different problems. These issues are then filed in a section of Chromium bug tracker, and after ~30 days, they are made public. When developers fix bugs of this kind, they refer to the issue number (for example 321) as ofz#321. A comprehensive list of all issues found is visible here:

• Chromium Bug Tracker – LibreOffice Issues

Fixing the Issues

Let’s look at one of the fixes. You can find commits related to fuzzing with:

$ git log --grep=ofz

This is a recent fix from Caolán, an experienced LibreOffice developer that provided most of …

In the previous blog post, I provided a brief introduction to LibreOfficeKit API which one can use for accessing LibreOffice functionalities in an external application. Here I discuss in detail how to use LibreOfficeKit for converting an ODT to PDF, or from/to virtually any other format that LibreOffice supports.

LibreOfficeKit C++ Headers

For this example, you only need one header: LibreOfficeKit/LibreOfficeKit.hxx. Include it, and that is enough. This header will be available in the future versions of LibreOffice community. But for now, you may need to download LibreOfficeKit headers folder from LibreOffice core source code, and put it alongside your source code.

C++ Example

The example is relatively short. Here it is:

#include <iostream>
#include <LibreOfficeKit/LibreOfficeKit.hxx>
int main(int argc, char *argv[])
{
    if(argc < 2)
    {
        std::cout << "Usage: lokconvert  \n";
        return 1;
    }
    const char *input = argv[1];
    const char *output = argv[2];

    lok::Office * llo = NULL;
    try
    {
        const char lo_path[] = LOROOT "/program/";
        llo = lok::lok_cpp_init(lo_path);
        if (!llo) {
            std::cerr << "Error: could not initialize LibreOfficeKit\n";
            return 1;
        }

        lok::Document * lodoc = llo->documentLoad(input, NULL /* options */);
        if (!lodoc) {
            std::cerr << "Error: could not load document: " << llo->getError() << "\n";
            return 1;
        }

        if (!lodoc->saveAs(output, "pdf", NULL /* options */))
        {
            std::cerr << "Error: could not export document: " << llo->getError() << "\n";
            return 1;
        }
    }
    catch (const std::exception & e)
    {
        std::cerr << "Error: LibreOfficeKit exception: " << e.what() << "\n";
        return 1;
    }

    std::cerr << "Success!\n";
    return 0;
}

The example is simple. Input and output file names are passed via command line arguments, and are received via argv[1] and argv[2], if argument count, argc, is at least 3. First one is the program name itself, which we don’t use here.

LibreOffice binary folder is needed here, so you should set OO_SDK_URE_BIN_DIR environment variable, or you may even set that in your program itself.

This part of the code is for LibreOfficeKit initialization:

llo = lok::lok_cpp_init(lo_bin_dir);

And after that, it is the time to load the document:

lok::Document* lodoc = llo->documentLoad(input, NULL /* options */);

Having the lodoc pointer is necessary for converting the document using saveAs function:

lodoc->saveAs(output, "pdf", NULL /* options */)

As you can see, relevant code is inside a try/catch block. In case some exception occur, you will see relevant error information on the console. Also, in each step, from initializing LibreOfficeKit, to loading and in the end generating the output, there are error handling mechanisms to make sure that the work goes forward smoothly.

In the end, if everything is successful, you will see this message on the screen:

Success!

Build with cmake

You can use cmake to build this example. Here is an example CMakeLists.txt which also provides LO_ROOT and LO_SDK_ROOT to be used inside C++ file, as an alternative to setting it via an environment variable, or putting it manually in the code.

cmake_minimum_required(VERSION 3.5)

project(lokconv LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(lokconv main.cpp)

include(GNUInstallDirs)

set(LOVERSION 24.2)

if(WIN32)
    set(LOROOT …