LibreOffice Development Blog

In LibreOffice C++ code, there are many cases where developers have string literals that should be used in the code. If these are messages in the graphical user interface (GUI), they should be added to the translatable messages. But, there are many cases where the string literals has nothing to do with other languages, and they should be used as they are. In this case, enumarray is helpful. Although they are not limited to string literals, and can be used for any data.

Using Symbolic Constants

In old C code, using #define was the preferred way one could give a name to a string literal or other kinds of data. For example, consider this code:

const char[] FRAME_PROPNAME_ASCII_DISPATCHRECORDERSUPPLIER = "DispatchRecorderSupplier";
const char[] FRAME_PROPNAME_ASCII_ISHIDDEN = "IsHidden";
inline constexpr OUString FRAME_PROPNAME_ASCII_LAYOUTMANAGER = "LayoutManager";
const char[] FRAME_PROPNAME_ASCII_TITLE = "Title"_ustr;
const char[] FRAME_PROPNAME_ASCII_INDICATORINTERCEPTION = "IndicatorInterception";
const char[] FRAME_PROPNAME_ASCII_URL = "URL";

And also, the relevant states:

#define FRAME_PROPHANDLE_DISPATCHRECORDERSUPPLIER 0
#define FRAME_PROPHANDLE_ISHIDDEN 1
#define FRAME_PROPHANDLE_LAYOUTMANAGER 2
#define FRAME_PROPHANDLE_TITLE 3
#define FRAME_PROPHANDLE_INDICATORINTERCEPTION 4
#define FRAME_PROPHANDLE_URL 5

Although this C code still works in C++, it is not the desired approach in modern C++.

Using enumarrays

In modern C++ code, you can use enumarry, which is defined in o3tl in LibreOffice. The above code becomes:

enum class FramePropNameASCII
{
    DispatcherRecorderSupplier,
    IsHidden,
    LayoutManager,
    Title,
    IndicatorInterception,
    URL,
    LAST=URL
};

And also, the string literal definitions:

constexpr o3tl::enumarray<FramePropNameASCII, OUString> FramePropName = {
    u"DispatchRecorderSupplier"_ustr,
    u"IsHidden"_ustr,
    u"LayoutManager"_ustr,
    u"Title"_ustr,
    u"IndicatorInterception"_ustr,
    u"URL"_ustr
};

Why an enumarray?

The names are much more readable, as they do not have to be ALL_CAPPS, as per convention for symbolic constants in C. Their usage is also quite easy. For example, one can use [] to access the relevant string literal:

- xPropSet->getPropertyValue( FRAME_PROPNAME_ASCII_LAYOUTMANAGER ) >>= xLayoutManager;
+ xPropSet->getPropertyValue( FramePropName[FramePropNameASCII::LayoutManager] ) >>= xLayoutManager;

Final Notes

In LibreOffice, enumarrays are not limited to string literals, and they can be used with other data. This task is filed as tdf#169155, and if you like, you may try finding some instances in the code and modernize it using enumarrays.

To learn more about LibreOffice development, you can refer to TDF Wiki. You may follow this blog to read about EasyHacks, tutorials and announcements related to LibreOffice development.

If you are working with LibreOffice code, trying to understand the code, fix bugs, or implement new features, you will need to debug the code at some point. Here are some general tips for a good debugging experience. Let’s start from the platform

Choose the Right Debug Platform

Choosing a platform to debug usually depends on the nature of the problem. If the problem is Windows-only, you need a Windows environment to build and debug the problem. But, if the problems can be reproduced everywhere, then you can choose the platform of your choice with the debugging tools that you prefer to debug the problem.

On Linux, it matters if you are running X11 or Wayland. Also, as there are multiple graphical back-ends available for LibreOffice, it matters if you are using X11, GTK3/4, or Qt5/6 back-end for your debugging. Some bugs are specific to GTK, then you should use GTK3 UI for testing. In 2025, GTK4 UI of LibreOffice is still experimental, so it is better to work with GTK3. For making the debugging easier, many developers work on X11 (gen) UI for debugging.

Debugging Tools

Various debugging tools can be used to debug the soffice.bin/soffice.exe LibreOffice binary that you have built. For the common debuggers, you can use GDB on Linux, lldb on macOS, and WinDbg or Visual Studio on Windows.

For using the above debuggers, you can use the IDE or front-end that support them. Various IDEs are usable with LibreOffice code. For a detailed explanation, refer to this Wiki article:

• TDF Wiki: Development/IDE

Make sure that you can build and debug a simple program before trying to build and debug LibreOffice.

Environment Variables

To have a better debugging experience, or to avoid problems you may have to customize the debugging session with environment variables. A complete article of the TDF Wiki is dedicated to discuss the environment variables that can be used with LibreOffice:

• TDF Wiki: Development/Environment variables

Here is some of the most important ones:

1) Using the X11 user interface:

If you want to use the X11 back-end that is simpler, and usually easier to work with on debug sessions, you have to set SAL_USE_VCLPLUGIN environment variable:

export SAL_USE_VCLPLUGIN=gen
That is specially useful when you are debugging graphical problems. But in some cases, you may need to avoid it or at least customize it. For example, while debugging mouse-related problems you may need to tell LibreOffice to avoid mouse grabbing this way:

export SAL_NO_MOUSEGRABS=1

2) Using GTK user interface

If you are using GTK user interface, then you may use GTK inspector to interactively debug LibreOffice GUI. You can use it this way:

export GTK_DEBUG=interactive

Pretty Printers

In solenv/gdb/ inside LibreOffice source code, you may find pretty printers for GDB. This is helpful when debugging LibreOffice with GDB, to be able to see data in a more readable way.

Dumping Data

Sometimes when you debug a LibreOffice application, it is easier to dump data into file for easier diagnosis. There are key combinations that are enabled in debug mode for this purpose. To use them, you need to build LibreOffice with the configuration option --enable-dbgutil.

These are some of them related to text boxes, rendered with editeng module:

• Ctrl+Alt+F11 – toggles dumping the edit engine state to the
  editenginedump.log on Draw
• Ctrl+Alt+F12 – dumps the current edit engine state to editenginedump.log

There are other key combinations for using in Writer and Draw:

• SW_DEBUG=1 enables F12 for dumping layout.xml, and Shift+F12 for nodes.xml which are Writer document dumps
• SD_DEBUG=1 enable F12 for model.xml which contains Draw graphic object dump

These key combinations can be used with Calc:

• Ctrl+Shift+F12: Dump the column width of the first 20 columns
• Ctrl+Shift+F11: Dump the graphic objects and their position and size in pixels
• Ctrl+Shift+F6: Dump the cell properties’ of the current selection as dump.xml

These key combinations help to debug some useful details about the application for diagnosis. They are only active in debug mode, as described.

Further Information

We have a complete TDF Wiki article dedicated to debugging. So, make sure that you take a look at the relevant parts:

• TDF Wiki: How to debug

Debugging needs patience, but can be the best way to find the root cause of some bugs.

LibreOffice handles different input and output formats, and also displays text and graphics alongside inside the GUI on computer displays. This requires LibreOffice to understand various different measurement units, and convert values from one to another.

Unit selection

The unit conversion can be done by writing extra code, where one should know the units, and calculate factor to convert them to each other.

For example, consider that we want to convert width from points into 1/100 mm, which is used in page setup.

We know that:

1 point = 1/72 inch
1 inch = 25.4 mm = 25400 microns
factor = 25400/(72*10) ≈ 35.27777778

Then, it is possible to write the conversion as:

static int PtTo10Mu( int nPoints )
{
return static_cast<int>((static_cast<double>(nPoints)*35.27777778)+0.5);
}

A separate function that casts integer nPoints to double, then multiplies it by the factor which has 8 decimal points, and then rounds the result by adding 0.5 and then truncates it and stores it in an integer. This approach is not always desirable. It is error-prone, and lacks enough accuracy. For big values, it can calculates values off by one.

Another approach is to use o3tl (OpenOffice.org template library) convert function. It is as simple as writing:

int nResult = o3tl::convert(nPoint, o3tl::Length::pt, o3tl::Length::mm100)

As you can see, it is much cleaner, and gives the output, properly rounded as an integer!

You need a double? No problem! You can use appropriate template to achieve that:

double fResult = o3tl::convert<double>(nPoint, o3tl::Length::pt, o3tl::Length::mm100)

These are the supported units, defined in the header include/o3tl/unit_conversion.hxx:

mm100 – 1/100th mm = 1 micron

mm10 – 1/10 mm

mm – millimeter

cm – centimeter

m – meter

km – kilometer

emu – English Metric Unit (1/360000 cm)

twip – Twentieth of a point (1/20 pt)

pt – Point (1/72 in)

pc – Pica (1/6 in)

in1000 – 1/1000 in

in100 – 1/100 in

in10 – 1/10 in

in – inch

ft – foot

mi – mile

master – PPT Master Unit (1/576 in)

px – Pixel unit (15 twip, 96 ppi)

ch – Char unit (210 twip, 14 px)

line – Line unit (312 twip)

Handling Overflows

If you are doing a conversion, it is possible that the result overflows. With o3tl::convert() you can handle it this way:

sal_Int64 width = o3tl::convert(nPoint, o3tl::Length::pt, o3tl::Length::mm100, overflow, 0);
if (overflow)
{
...
}

Code Pointers

To to find instances to change, one can try finding some magic numbers listed here. For example, consider measuring a line based on twips:

line – Line unit (312 twip)

If you search for 312, you may find some examples:

$ git grep -w 312 *.cxx

Final Words

The task described here is filed as tdf#168226:

• Use o3tl::convert() for unit conversion instead of custom formula

EasyHacks are well-defined small tasks that are designed to help newcomers begin LibreOffice programming. If you like it, you can start working on it!

Using o3tl::convert() not only simplifies the unit conversion, but it also improves the accuracy. There is a possibility to handle overflow, which is not easily possible if you do the conversion manually. Therefore, unit conversion using this function is usually the best option in LibreOffice.

If you need help starting LibreOffice coding, make sure that you see this tutorial first:

Getting Started (Video Tutorial)

LibreOffice inherits a gigantic code base from its ancestors, StarOffice and OpenOffice. Here I discuss some notes for the newcomers on how to better understand the existing LibreOffice code, and improve the patches.

Studying the Existing Code

As said, LibreOffice is a huge code base, containing ~10 million lines of mostly C++ code. There are different assumptions, conventions and coding styles across ~200 modules that LibreOffice has.

Therefore, it is important to first, study the existing code, through reading and debugging LibreOffice source code, to understand the things that it does, and the way you can implement your ideas, including bug fixes and adding new features.

And although implementing some ideas seem to be straightforward at first sight, it is meaningful to study the details.

Quality Assurance Point of View

First of all, you should understand the thing that you want to implement. No matter if it is a bug, a new feature, or just an EasyHack, you should understand what is requested, what works and what does not work. This requires careful reading of the Bugzilla pages.

User Point of View

Then, you should try to run LibreOffice to understand the exact place in the application where you want to change. LibreOffice user interface has thousands of dialog boxes, so you need to make sure that you understand the thing that you want to do.

Developer Point of View

And at last, you get into implementing something in the code. Here are some questions that you can ask yourself about the details, when reading the existing code:

• Why this statement is here, in the first place? (detail-oriented view)
  • You can use git blame to see the last author of a specific line
  • You can use git log to study the details by knowing the commit hash
  • What can this part of code actually does?
  • Can I see its effect?

git log

Or, you may be interested in the code behavior in the big picture:

• What does the code do as a whole? (holistic view)
• There are many other statements, functions and other constructs in the code. What do they do?
• What is the overall goal of the code?
• Can I test that in action?

You can do some small changes, before even getting into implementing your idea:

• What happens if I remove it? (small changes)
• Does the removal prevent the code from working?
• Is it incomplete, or does it actually do something useful, which
• will be absent if I remove it?

Then, you can work on the actual implementation. Ask yourself:

• How can I implement the idea in its simplest form? (straightforward change)
• Does it have side effects?
• How can I make sure every thing else works as before?
• How can I write a test for it?

After understanding some of the basic details about the way things work, you may go into improving your implementation.

• How can I make it better? (sophisticated change)
• Can I make the code more robust where it is brittle?
• Can I complete the code where it is incomplete?

Final Notes

These were the questions to give you some ideas of some of the underlying complexities in the code. You can start from small changes to become familiar with these complexities, and then grow to do more complex stuff in the code.

We have various different EasyHacks in LibreOffice, with different difficulty levels. If you are interested in coding, you can always find something that fits you, and grow gradually.

You can read more in these links:

• TDF Wiki: EasyHacks
• Blog posts on some (solved) difficultyInteresting EasyHacks

Happy new year 2025! I wish a great year for you, and the global LibreOffice community. Now that we are now in 2025, I briefly discuss the year 2024 and outlook for 2024 in the development blog.

LibreOffice Conference 2024, Luxembourg

At The Document Foundation (TDF), our aim is to improve LibreOffice, the leading free/open source office suite that has millions of users around the world. Our work is community-driven, and the software needs your contribution to become better, and work in a way that you like.

My goal here, is to help people understand LibreOffice code easier, and eventually participate in LibreOffice core development to make LibreOffice better for everyone. In 2024, I wrote 22 posts around LibreOffice development in the dev blog (4 of them are unpublished drafts).

Outlook For the New Year

Focus of the development blog for 2025 in this blog will be:

• Introducing new EasyHacks
• Describing user interface creation with VCL
• Explaining LibreOffice architecture
• Explaining Python interaction with LibreOffice

I have written about some of these topics in 2024. Therefore, this year I will try to expand the previous writings and provide new articles about them. For example, creating user interfaces using VCL with the help of glade interface designer will be one of important things to discuss.

You can give feedback by writing a comment here, or sending me an email to hossein AT libreoffice DOT org.

We provide mentoring support to those who want to start LibreOffice development. You are welcome to contact me if you need help to build LibreOffice and do some EasyHacks via the above email address. Also, you can always refer to our Getting Involved Wiki page:

• TDF Wiki: Getting Involved in LibreOffice Development

Let’s hope a great year for LibreOffice (and the world) in 2025.