VCL example applications and tools

You may already know that LibreOffice uses its internal GUI toolkit, named VCL (Visual Class Library). This library is responsible for creating the GUI widgets for LibreOffice, providing abstraction from the operating system including the basic rendering. To see more details, you can read its documentation page:

• Visual Class Library (VCL)

VCL has the nice feature of being able to work with different GUI libraries on different platforms. For example, if you are on Linux, you can use X11, Gtk3/4, Qt, or KDE back-ends for the VCL applications like LibreOffice. You can easily switch between them by using the environment variable SAL_USE_VCLPLUGIN. For example, you can use the old style X11 GUI in this way:

SAL_USE_VCLPLUGIN=gen instdir/program/soffice

Or, by passing it to the LibreOffice program itself:

instdir/program/soffice -env:SAL_USE_VCLPLUGIN=gen

In addition, there are other GUI backends, or plugins which are as follows:

You can read more about the related environment variables here:

• Environment variables in VCL

The code for the library is available in the vcl/ folder inside core source code. Also, beside the main source code and tests, there is a folder named workbench. Inside this folder, you can find several standalone VCL applications:

VCL Applications and Workbenches

vcldemo: This is a showcase of some of the VCL rendering abilities including the lines, shapes, internationalized text, pictures and more! You can see run this demo by invoking this command, after you could be able to build LibreOffice:

./bin/run vcldemo

vcldemo

minvcl: This is possibly one of the smallest example application that is possible with VCL. Basically, It creates a window and draws a simple text inside it. Likewise, you can run it by invoking:

./bin/run minvcl

minvcl

Image Tools

icontest: This bitmap image testing is used by some of the developers to test VCL bitmap rendering capabilities. It can be invoked this way:

./bin/run icontest <image>

mtfdemo: This is a small application for displaying and dumping the structure of EMF/EMF+/WMF files, which is a vector image format from Microsoft. This is previously discussed in another blog post here:

• Supporting metafile formats: WMF/EMF/EMF+

Similarly, it can be run in this way:

./bin/run mtfdemo <emf|wmf image>

Font Tools

listfonts: This utility lists the current list of fonts installed in the system, and the features of each font. To display the information on the screen, you can invoke it this way:

./bin/run listfonts --

listglyphs: This utility lists the current glyphs in a font that is already installed on the system. You should provide the font name to it, in this way:

./bin/run listglyphs FreeMono --

VCL Fuzzers and Platform Specific Tools

Beyond the above applications and tools, there are many other platform specific tools that are not available on each and every platform. Also, there are many fuzzers ans testing tools that are helpful for fuzz-testing the library. You can find the complete list of executables using this command:

ls vcl/Executable_*.mk

As can be seen in the output, many of them are fuzzers. To use the fuzzers, first you have to setup the oss-fuzz via ./bin/oss-fuzz-setup.sh script. Then, you may be able to build the fuzzers using ./bin/oss-fuzz-build.sh script. Make sure that you have $OUT, $SRC and $WORK environment variables to set the fuzzer build environment. Be ready for several tarballs and archives downloads at first. You will need curl and svn to continue.

Final Notes

These tools and small applications and their source code are good for testing and getting to understand the VCL library better. As a suggestion, you can start from the minvcl.cxx to understand how to create a GUI application that can work across various platforms with different GUI toolkits. Hopefully, I will discuss the source code of some of these examples in the later blog posts.