GSoC 2023 Final Project Report
Project Title
Make GNOME Platform demos and create offline documentation viewer for Workbench
Mentors
Sonny Piers, Andy Holmes
About The Project
Workbench is an application that lets you experiment and tinker with GNOME technologies. It’s aimed at beginners who want to get into GTK development or developers who want to prototype a feature for their apps.
Workbench comes with a “Library” which is a collection of demos, made to showcase the widgets, APIs, and design patterns of GTK. The demos are made in such a way that they are easy to understand for beginners and highlight only commonly used parts of a widget or an API. The demos can be a good reference for developers who simply want to look up the usage of a widget without going through piles of documentation and directly copy code snippets from the demos.
The main goal of my GSoC project was to create as many demos as possible for Workbench. Since there were a total of 3 students working on the project (2 GSoC and 1 Outreachy), we later decided that our goal was to try and reach 100 demos in the Library. We focused on making demos in GNOME JavaScript and they can be later ported to other languages.
I also worked on creating a Documentation Viewer for Workbench.
The Demos
I made 31 demos for Workbench during the entire GSoC period. The demos cover widgets and APIs from various GNOME libraries — Gtk, Adwaita, Gio, Xdp, and Shumate. I have listed all the demos with links to the PRs and the widget/API they cover below.
- Avatar —
AdwAvatar - Text Fields —
GtkEntry,GtkEntryCompletion,GtkPasswordEntry - Box —
GtkBox - Color Dialog —
GtkColorDialog,GtkColorDialogButton - Level Bars —
GtkLevelBar - Overlay —
GtkOverlay - Header Bar —
AdwHeaderBar - Web View —
WebKitWebView - Advanced Buttons —
AdwSplitButton,AdwButtonContent - Tab View —
AdwTabView - Animation —
AdwAnimation - Spin Button —
GtkSpinButton - Banner —
AdwBanner - Progress Bar —
GtkProgressBar - Revealer —
GtkRevealer - Check Button —
GtkCheckButton - Search —
GtkSearchBar,GtkSearchEntry - Map —
Shumate-1.0 - Actions —
GAction - Flow Box —
GtkFlowBox - Emoji Chooser —
GtkEmojiChooser - Tooltip —
GtkTooltip - Link Button —
GtkLinkButton - Scrolled Window —
GtkScrolledWindow - Image —
GtkImage - Menu —
GMenu - Navigation Split View —
AdwNavigationSplitView - Network Monitor —
GNetworkMonitor - Power Profile Monitor —
GPowerProfileMonitor - Session Monitor and Inhibit —
XdpPortal.session_monitor_start,XdpPortal.session_monitor_inhibit - Memory Monitor —
GMemoryMonitor
I would love to talk about each of these demos but to keep it short, here are some notable ones for me.
Avatar
While this was a very simple demo, it was one of my first contributions. I learned a lot about GTK and Blueprint from this one simple demo. The “Image…” button lets the user select an image locally using GtkFileDialog which was new at the time. It makes use of the Gio._promisfy pattern to present the dialog asynchronously.
Box
GtkBox is a very commonly used widget, it’s a container that arranges its children into a single row or column. It can be hard for beginners to understand or visualize a box, especially with the various alignment properties. We decided to create an interactive demo for this so that users can play around with the widget and learn.
Web View
WebView provides an easy way to load HTML pages and websites in your apps. Making this demo I learned a lot about WebView, and trying to showcase it in a neat way (both in code and UI) was a little challenging but fun.
Animation
AdwAnimation is a simple API that lets you create timed and spring animations. This demo turned out challenging because I had some trouble working with Adw.CallbackAnimationTarget which is used to animate a custom property by updating it using a callback function. I managed to figure it out in the end, and the result was very satisfying.
Map
libshumate is a library that is used to display and render maps. I had never worked with it before so it did take me some time to learn. It was one of the first demos that covered a library outside of org.gnome.Platform.
Actions and Menus
GAction is a very useful API that’s used throughout GTK and GMenu is a way to visually present Actions to the user. Actions can also appear as different types and it was important the demo made the distinction between those. Since Menus and Actions are very closely connected, it was hard to separate those out into two different demos. I brainstormed some ideas with Andy and I am happy with the way the demo turned out. Andy also updated the GJS Guide to talk about Actions and Menus as a way to complement the demo.
Flow Box
GtkFlowBox is a container that arranges its child widgets into a grid, and when the container is resized it’ll readjust the number of columns of the grid. We got a little creative with this demo ;)
Network Monitor
GNetworkMonitor is a simple Gio API that monitors your network status. This demo was quite tricky to make because it was hard to test the demo and we had to find a way to inform the user on how to do that. We came up with the idea of including instructions in the demo and hiding them away in a popover.
After continuous 3 months of effort, I am very happy to say they we hit our combined goal of reaching 100 demos in the Library 🎉
Documentation Viewer
Halfway through GSoC, Sonny gave us an opportunity to take a break from making demos and work on some features for Workbench. I decided to work on providing offline documentation for Workbench. This can be useful because jumping back and forth between Workbench and documentation can be annoying sometimes and there may be times when you don’t have access to a good internet connection.
To get the documentation, it made sense to make use of the SDK that GNOME provides for documentation which is org.gnome.Sdk.Docs. The first iteration of the Documentation Viewer was very simple, it showed all the available namespaces of docs, and clicking on any item on the sidebar loaded the main page of the documentation in a WebView. Since the sidebar was just a flat list for now and only had a few items, we decided to use a ListBox to display the items.
This was a great start but it wasn’t very useful because it was difficult to navigate and browse through the docs.
Then there were some follow-ups that made minor improvements to the Documentation Viewer, for example, filtering out irrelevant and outdated docs that weren’t needed and including some docs that were initially missing from the sidebar.
After this, I made a massive improvement to the Documentation Viewer in a follow-up PR.
- I ported the Documentation Viewer to GNOME 45 and improved the design by using the new
libadwaita 1.4widgets such as theNavigationSplitViewfor the sidebar. - I switched the
ListBoxfor aListViewand made use of aGtkTreeListModelandGtkTreeExpanderto show all the documentation under a given namespace as different sections using collapsible expanders. - We also decided to rename the Documentation Viewer as “Manuals”.
Finally, I worked on a basic searching feature inside Manuals to be able to search for specific documentation. While the search is not very good, it’s good enough for now. I’m relying on a GtkFilterListModel to filter out all the docs, it simply checks if the search term is a substring in any of the items or not. I also refactored a lot of code in this PR, to simplify the loading of docs and cleaned up code.
There is still work left to be done for Manuals such as optimizing the loading of documentation, implementing better search, and synchronizing the item selected in the sidebar and the doc shown in the webview. We are also planning to make this into a standalone app in the future.
Acknowledgments
I would like to thank my mentors, Sonny Piers and Andy Holmes, for their constant guidance and support throughout the project.
I would also like to thank GNOME for sponsoring my first overseas trip to attend GUADEC 2023.