mirror of
https://github.com/LadybirdBrowser/ladybird
synced 2026-04-25 17:25:08 +02:00
Documentation: Add GTK UI build prerequisites and style guide
Add GTK4/libadwaita build instructions alongside Qt. Add Documentation/GtkFrontend.md with GTK-specific coding style rules and a manual test checklist.
This commit is contained in:
Notes:
github-actions[bot]
2026-04-17 15:19:05 +00:00
Author: https://github.com/jdahlin Commit: https://github.com/LadybirdBrowser/ladybird/commit/6c99bf74eaa Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/8691 Reviewed-by: https://github.com/ADKaster Reviewed-by: https://github.com/christianfrey Reviewed-by: https://github.com/cqundefine Reviewed-by: https://github.com/trflynn89 ✅
@@ -252,14 +252,35 @@ If you want to run other applications, such as the JS REPL or the WebAssembly RE
|
||||
Ladybird will be built with one of the following browser frontends, depending on the platform:
|
||||
* [AppKit](https://developer.apple.com/documentation/appkit?language=objc) - The native UI on macOS.
|
||||
* [Qt](https://doc.qt.io/qt-6/) - The UI used on all other platforms.
|
||||
* [GTK 4](https://docs.gtk.org/gtk4/) - An alternative UI on Linux (experimental).
|
||||
* [Android UI](https://developer.android.com/develop/ui) - The native UI on Android.
|
||||
|
||||
The Qt UI is available on platforms where it is not the default as well (except on Android).
|
||||
You can pick the UI using the `LADYBIRD_GUI_FRAMEWORK` option, for example to enable the Qt UI:
|
||||
The Qt and GTK UIs are available on Linux. You can pick the UI using the `LADYBIRD_GUI_FRAMEWORK` option:
|
||||
|
||||
```bash
|
||||
# From /path/to/ladybird
|
||||
cmake --preset Release -DLADYBIRD_GUI_FRAMEWORK=Qt
|
||||
cmake --preset Release -DLADYBIRD_GUI_FRAMEWORK=Gtk
|
||||
```
|
||||
|
||||
#### Additional prerequisites for the GTK UI
|
||||
|
||||
Building with `LADYBIRD_GUI_FRAMEWORK=Gtk` requires additional system packages, as some vcpkg
|
||||
dependencies (e.g. gettext) need to be rebuilt from source:
|
||||
|
||||
**Debian/Ubuntu:**
|
||||
```bash
|
||||
sudo apt install bison libxkbcommon-dev
|
||||
```
|
||||
|
||||
**Arch Linux/Manjaro:**
|
||||
```bash
|
||||
sudo pacman -S bison
|
||||
```
|
||||
|
||||
**Fedora:**
|
||||
```bash
|
||||
sudo dnf install bison
|
||||
```
|
||||
|
||||
### Build error messages you may encounter
|
||||
|
||||
105
Documentation/GtkFrontend.md
Normal file
105
Documentation/GtkFrontend.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# GTK Frontend
|
||||
|
||||
GTK4/libadwaita frontend for Ladybird.
|
||||
|
||||
## Style Guide
|
||||
|
||||
Follow the project [Coding Style](CodingStyle.md). Prefer C++ over C idioms wherever possible. Below are GTK-specific rules.
|
||||
|
||||
### General
|
||||
- Do not duplicate functionality already in LibWebView — the frontend is a thin shell
|
||||
- Follow [GNOME HIG](https://developer.gnome.org/hig/) — prefer libadwaita widgets (`AdwTabView`, `AdwHeaderBar`, `AdwAlertDialog`, `AdwToast`, etc.) over custom implementations
|
||||
- Prefer C++ types and patterns over GLib/GObject equivalents
|
||||
- Use D-Bus via `GApplication` for single-instance and IPC — not custom socket/file mechanisms
|
||||
- Prefer file-static functions over anonymous namespaces for internal helpers
|
||||
- Namespace: `Ladybird::` for C++ classes, `LadybirdWidgets::` for GObject widget helpers
|
||||
|
||||
### GObject
|
||||
- Only register GTypes (`G_DEFINE_FINAL_TYPE`) for widgets used in GtkBuilder templates
|
||||
- No `G_DECLARE_FINAL_TYPE` — define structs and `GType` functions manually to avoid reserved `_TypeName` names
|
||||
- Use `GtkBuilder` and `.ui` resource files for declarative layout where practical
|
||||
|
||||
### Signals and Callbacks
|
||||
- No `bind_template_callback` — connect signals in C++ with `g_signal_connect_swapped`
|
||||
- No `g_signal_new` — use `Function<>` callbacks instead of custom GObject signals
|
||||
- Prefer `g_signal_connect_swapped` over `g_signal_connect` to avoid `static_cast<Foo*>(user_data)`
|
||||
- For buttons in popover menus, prefer `action-name` properties over click signal handlers
|
||||
|
||||
### Memory Management
|
||||
- No manual `g_object_unref` — use `GObjectPtr<T>` (see `UI/Gtk/GLibPtr.h`)
|
||||
- No manual `g_free` — use `g_autofree`
|
||||
|
||||
```cpp
|
||||
// Local scope — auto-unrefs when out of scope
|
||||
GObjectPtr builder { gtk_builder_new_from_resource("/path/to/file.ui") };
|
||||
|
||||
// Class member
|
||||
GObjectPtr<GdkTexture> m_texture;
|
||||
m_texture = GObjectPtr<GdkTexture> { gdk_memory_texture_builder_build(builder) };
|
||||
|
||||
// g_autofree for glib-allocated strings
|
||||
g_autofree char* path = g_file_get_path(file);
|
||||
```
|
||||
|
||||
## Test Checklist
|
||||
|
||||
### Navigation
|
||||
- [ ] Load URL from location bar
|
||||
- [ ] Back/forward buttons
|
||||
- [ ] Reload (Ctrl+R, F5)
|
||||
- [ ] New tab (Ctrl+T)
|
||||
- [ ] Close tab (Ctrl+W)
|
||||
- [ ] New window (Ctrl+N)
|
||||
- [ ] Tab switching
|
||||
- [ ] Child tab creation (target=_blank)
|
||||
|
||||
### Input
|
||||
- [ ] Keyboard input in web content
|
||||
- [ ] Mouse clicks, drag, selection
|
||||
- [ ] Touchpad smooth scrolling
|
||||
- [ ] Mouse wheel discrete scrolling
|
||||
- [ ] Ctrl+scroll zoom
|
||||
- [ ] Right-click context menus (page, link, image, media)
|
||||
|
||||
### UI
|
||||
- [ ] Location bar URL display with domain highlighting
|
||||
- [ ] Location bar autocomplete
|
||||
- [ ] Security icon (https/insecure)
|
||||
- [ ] Find in page (Ctrl+F)
|
||||
- [ ] Fullscreen (F11)
|
||||
- [ ] Zoom in/out/reset (Ctrl+=/-/0)
|
||||
- [ ] Tab loading indicator
|
||||
- [ ] Cursor changes (pointer, text, resize, etc.)
|
||||
- [ ] Tooltips on hover
|
||||
- [ ] Dark/light theme follows system
|
||||
|
||||
### Dialogs
|
||||
- [ ] JavaScript alert
|
||||
- [ ] JavaScript confirm
|
||||
- [ ] JavaScript prompt
|
||||
- [ ] Color picker
|
||||
- [ ] File picker (single and multiple)
|
||||
- [ ] Select dropdown
|
||||
- [ ] Download save dialog
|
||||
- [ ] Download confirmation toast
|
||||
- [ ] Error dialog
|
||||
|
||||
### Window Management
|
||||
- [ ] Minimize/maximize/close
|
||||
- [ ] Resize
|
||||
- [ ] Fullscreen enter/exit
|
||||
- [ ] D-Bus single instance (second launch opens tab in existing window)
|
||||
|
||||
### Internal Pages
|
||||
- [ ] about:version
|
||||
- [ ] about:settings
|
||||
- [ ] about:processes (Task Manager)
|
||||
|
||||
### Clipboard
|
||||
- [ ] Copy (Ctrl+C)
|
||||
- [ ] Paste (Ctrl+V)
|
||||
- [ ] Select all (Ctrl+A)
|
||||
|
||||
### DevTools
|
||||
- [ ] Enable/disable via banner
|
||||
- [ ] Toggle (Ctrl+Shift+I, F12)
|
||||
Reference in New Issue
Block a user