Notebookbar part 1: custom widgets for the tabbed interface
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:
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.
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 on context" name="sfxlo-ContextVBox" generic-name="ContextVBox" parent="GtkBox" icon-name="widget-gtk-box"/> <glade-widget-class title="Managed Menu Button" name="svtlo-ManagedMenuButton" generic-name="ManagedMenuButton" parent="GtkButton" icon-name="widget-gtk-button"/> <glade-widget-class title="NotebookBar Toolbar Addons" name="NotebookBarAddonsToolMergePoint" generic-name="ShowText" parent="GtkToolButton" icon-name="widget-gtk-toolbutton"/> <glade-widget-class title="NotebookBar MenuItem Addons" name="NotebookBarAddonsMenuMergePoint" generic-name="ShowText" parent="GtkMenuItem" icon-name="widget-gtk-menuitem"/>
The previous xml shows the custom widgets that are building blocks of building Notebookbar. Let’s look into each of them, based on their title and names.
In the next picture, you can see the notebookbar in LibreOffice, and compare it to what is visible in Glade user interface designer. As you can see, not everything is visible in the designer. Specifically, icons and text are not visible in the designer but are visible in the final application.
Main Widget
1. Notebookbar Tab Control: This widget has the name sfxlo-NotebookbarTabControl
, and is the primary widget for Notebookbar. It can change the set of visible tabs based on the user context. Its parent class is GtkNotebook
and provides context-sensitive tab switching.
Container Widgets
2. NotebookbarToolBox: This widget is named sfxlo-NotebookbarToolBox
, its parent class is GtkToolbar
. It can contain toolbar elements.
3. Priority Horizontal Box: This widget has the name sfxlo-PriorityHBox
, and its parent class is GtkBox
. It is the horizontal box hiding children depending on its priorities. In this way, lower priority widgets becomes hidden to give the more important widgets room to be displayed on a screen that is not big enough to show all the available elements.
4. Priority Merged Horizontal Box: This widget has the name sfxlo-PriorityMergedHBox
, and its parent class is GtkBox
. It is the “horizontal box hiding children depending on its priorities”. This widget is also related to the previous one for creating more room for important widgets, but it is used inside the PriorityHBox
.
5. Optional Box: This widget has the name VclOptionalBox
, and its parent class is GtkBox
. This “box which can hide own content”, is a widget that is useful for creating small areas dedicated to a specific purpose. For example, you may see Home-Section-Clipboard
, which is used to define an area for clipboard related tasks inside Home tab.
6. Contextual Vertical Box: This widget has the name sfxlo-ContextVBox
and is a “vertical box hiding children depending on context” and its parent class is GtkBox
. It provides a box that can act based on the context, showing and hiding its children accordingly. You may look into sw/uiconfig/swriter/ui/notebookbar_single.ui
, which provides an example use.
Here is the correct control hierarchy, as depicted and described in the TDF Wiki:
Menu Widgets
7. Dropdown Box: This widget has the name sfxlo-DropdownBox
, its parent class is GtkBox
and is a “box which can move own content to the popup”. This is also useful where the space for the tabbed interface is not big enough. The menu, is what you can see in “File” and “Help” menu in every notebookbar in LibreOffice tabbed interface. Please note that only 1 GtkBox child should be inside it, so that the popup works properly. In fact, the above diagram shows the correct usage.
8. Managed Menu Button: This widget has the name svtlo-ManagedMenuButton
, and its parent class is GtkButton
. It is a “Managed Menu Button”. It provides a button that opens a dynamic menu which is populated according to the context.
Custom Widgets for the Extensions
9. NotebookBar MenuItem Addons: This widget has the name NotebookBarAddonsToolMergePoint
, and its parent class is GtkToolButton
. Specifically, LibreOffice extensions can use it for adding additional tools to the notebookbar.
10. NotebookBar MenuItem Addons: This widget has the name NotebookBarAddonsMenuMergePoint
, and its parent class is GtkMenuItem
. This is also used for adding extra items into the notebookbar.
Final Notes
You can find useful information about Notebookbar in the design team blog:
- Easyhacking: How to set up your environment
- DIY UI: How to create your own Notebookbar
- Evolving Past the Restrictions of Toolbars
And at last, these are some useful Wiki articles around Notebookbar in the TDF Wiki:
Thank you very much for the post on GTK custom widgets for the tabbed interface. Does this only apply to GTK3 or also to the GTK4 version of LibreOffice?
As far as I understood, the GTK4 LibreOffice UI is going to replace the old GTK3 version. Is there an approximate timeframe for this? E.g. for LibreOffice 25.2 or 25.10?
Hello Gerry, you’re welcome.
This is about VCL weld mechanism, which reads the UI design from the
.ui
files created by glade, but creates the GUI with whatever VCL UI plugin that you are specifying. If it is GTK3, then you will get a GTK3 UI, and if it is GTK4, Qt, Windows, or other VCL UI plugins, the LibreOffice UI will be displayed accordingly.https://wiki.documentfoundation.org/Development/Environment_variables#VCL
Please note that you have to have build that specific VCL UI plugin from sources.
https://wiki.documentfoundation.org/Development/GTK4
GTK4 UI plugin is still experimental, so GTK3 will remain active in the foreseeable future, and the possible transition will not likely to happen in LO 25.2 or 25.10. Anyway, discussing that on #libreoffice-dev IRC is more meaningful, as many developers are there.