Wayland CSD: Document the new decorations and remove the standalone tests

The standalone C tests compiled the glfw sources by including them and
stubbing internals and were not run by the test suite. Move the useful
parts of the markdown docs into the option docs and changelog.
This commit is contained in:
Kovid Goyal 2026-10-30 09:07:45 +05:30
parent e37f4cd223
commit 84b93bd01c
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
5 changed files with 12 additions and 379 deletions

View file

@ -231,6 +231,11 @@ Detailed list of changes
0.50.0 [future]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Wayland: The client side window decorations used on compositors such as
GNOME now look like native GNOME decorations and follow the desktop titlebar
font, text scaling, button layout and titlebar click action settings
(:pull:`10766`)
- A new option :opt:`hyperlink_target_position` to control where the URL shown
by :opt:`show_hyperlink_targets` is displayed, including as a browser style
tooltip next to the mouse cursor (:iss:`10770`)

View file

@ -1,98 +0,0 @@
# Built-in GNOME-style Wayland decorations
Kitty's client-side decorations use a GNOME-style software renderer. It does not
use GTK, libadwaita, a hidden helper window, or a new library dependency. This is
the only CSD renderer; no environment variable or special build flag is needed.
Existing compositor/server-side decoration negotiation is unchanged.
Build normally, then run from this checkout:
```sh
python3 setup.py build
./kitty/launcher/kitty \
-o linux_display_server=wayland -o hide_window_decorations=no \
-o wayland_titlebar_color=system
```
The renderer draws a header of at least 38 logical pixels, centered title,
24-pixel circular controls spaced 36 pixels apart, antialiased upper corners
and matching shadows. The header grows to accommodate the selected font and
text scale. Maximized/tiled headers have square corners. Narrow headers hide
minimize/maximize controls before close, when those controls are configured.
A control activates only after a matching press/release.
With `wayland_titlebar_color system`, the palette follows the desktop's color
scheme, including live light/dark transitions. GNOME reports its normal light
appearance as "no preference"; this uses the light palette, independent of the
terminal background. If the portal or color-scheme setting is unavailable, the
fallback is dark; a valid "no preference" reply remains distinguishable from
missing settings. Explicit colors still
take precedence, with contrasting text and controls.
The existing asynchronous portal query also reads these GNOME settings:
| Namespace | Settings used |
| --- | --- |
| `org.gnome.desktop.interface` | `font-name`, `text-scaling-factor` |
| `org.gnome.desktop.wm.preferences` | `titlebar-font`, `titlebar-uses-system-font`, `button-layout` |
| `org.gnome.desktop.wm.preferences` | `action-double-click-titlebar`, `action-middle-click-titlebar`, `action-right-click-titlebar` |
These affect the titlebar, not terminal text. Font preferences select either
GNOME's interface font (bold for the title) or the configured title font.
Family, point size and trailing Bold/Italic/Oblique/Regular/Normal styles are
supported through FreeType/Fontconfig. Text scale is validated between 0.5 and
4.0. Font or scale changes rebuild the cached font/header as needed. Normal
windows keep their terminal content size; docked windows keep their exterior
size while the header changes height.
Button layout respects left/right placement, ordering and omitted controls.
Duplicate or unsupported control names are ignored; malformed layouts retain
the last valid layout. Supported titlebar actions are menu, toggle-maximize,
minimize and none. Unsupported actions such as lower, shade or single-axis
maximize are treated as no action; no equivalent xdg-shell request is used.
Updates are applied live through portal SettingChanged signals, without a new
settings subprocess or blocking query. On backends that omit these GNOME keys,
fallbacks are sans-serif 11, scale 1, controls minimize/maximize/close on the
right, double-click maximize, right-click menu and no middle-click action.
This approximates GNOME appearance. GTK/Yaru CSS, arbitrary Pango font styling,
theme-specific decoration palettes, icon artwork and shadow geometry are not
interpreted. Lower terminal corners remain square. Visual review used Ubuntu
26.10 / GNOME Shell 51.0; Ubuntu 24.10 has not been tested.
The rounded header cutouts contain the same shadow field as the adjacent
surfaces, including inactive opacity. A smooth outer envelope removes the finite
blur buffer's rectangular outline. Shadows use a cached tile, without a
full-window atlas.
## Validation
The renderer test checks buffer bounds at 100/125/150/200% scale, tiny/narrow/normal
widths, focused/unfocused/maximized states, dark/light/dark repainting, explicit
custom colors, control spacing, split/empty layouts, narrow-window priorities,
header growth and header/shadow continuity. A separate test feeds real D-Bus
settings signal messages through the handler to validate appearance, font
selection, text scale, invalid values, duplicate controls and titlebar actions,
without changing desktop settings.
From the repository root:
```sh
gcc -D_GLFW_WAYLAND -Iglfw $(pkg-config --cflags dbus-1) \
-Wall -Wextra -Werror -Wno-missing-field-initializers -std=c11 -pedantic-errors \
-ffunction-sections -fdata-sections glfw/tests/gnome_csd.c \
-Wl,--gc-sections $(pkg-config --libs wayland-client) -lm -o /tmp/kitty-csd-test
/tmp/kitty-csd-test
gcc -D_GLFW_WAYLAND -Iglfw $(pkg-config --cflags dbus-1) \
-Wall -Wextra -Werror -Wno-missing-field-initializers -std=c11 -pedantic-errors \
-ffunction-sections -fdata-sections glfw/tests/desktop_appearance.c glfw/dbus_glfw.c \
-Wl,--gc-sections $(pkg-config --libs dbus-1) -lm -o /tmp/kitty-appearance-test
/tmp/kitty-appearance-test
```
Add `-fsanitize=address,undefined` to the renderer test for memory/UB checks. It
writes a preview to `/tmp/kitty-gnome-csd-preview.ppm`. Manual compositor review
should also cover dynamic/Unicode titles, maximize/restore, fullscreen, focus,
custom colors, theme changes and cancelled button presses.

View file

@ -1,134 +0,0 @@
#define _POSIX_C_SOURCE 200809L
/* Exercise portal appearance replies/signals without changing desktop settings. */
#include "../linux_desktop_settings.c"
#include <assert.h>
#include <stdarg.h>
_GLFWlibrary _glfw;
static unsigned redraws;
GLFWAPI void glfwWaylandRedrawCSDWindowTitle(GLFWwindow *window) { (void)window; redraws++; }
void _glfwInputError(int code, const char *format, ...) { (void)code; (void)format; abort(); }
static unsigned notifications;
static GLFWColorScheme received;
void
_glfwInputColorScheme(GLFWColorScheme value, bool initial) {
(void)initial;
notifications++;
received = value;
}
static void
change_scheme(uint32_t value) {
DBusMessage *msg = dbus_message_new_signal(DESKTOP_PATH, DESKTOP_INTERFACE, "SettingChanged");
assert(msg);
const char *namespace = FDO_DESKTOP_NAMESPACE, *key = FDO_APPEARANCE_KEY;
DBusMessageIter iter, variant;
dbus_message_iter_init_append(msg, &iter);
assert(dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &namespace));
assert(dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &key));
assert(dbus_message_iter_open_container(&iter, DBUS_TYPE_VARIANT, "u", &variant));
assert(dbus_message_iter_append_basic(&variant, DBUS_TYPE_UINT32, &value));
assert(dbus_message_iter_close_container(&iter, &variant));
setting_changed(NULL, msg, NULL);
dbus_message_unref(msg);
}
static void
change_setting(const char *namespace, const char *key, int type, const void *data) {
DBusMessage *msg = dbus_message_new_signal(DESKTOP_PATH, DESKTOP_INTERFACE, "SettingChanged");
assert(msg);
DBusMessageIter iter, variant;
char signature[] = {(char)type, 0};
dbus_message_iter_init_append(msg, &iter);
assert(dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &namespace));
assert(dbus_message_iter_append_basic(&iter, DBUS_TYPE_STRING, &key));
assert(dbus_message_iter_open_container(&iter, DBUS_TYPE_VARIANT, signature, &variant));
assert(dbus_message_iter_append_basic(&variant, type, data));
assert(dbus_message_iter_close_container(&iter, &variant));
setting_changed(NULL, msg, NULL);
dbus_message_unref(msg);
}
int
main(void) {
assert(!glfw_has_system_color_theme());
// An attempted/failed query must not hide a later initial reply containing 0.
appearance_initialized = true;
DBusMessage *reply = dbus_message_new(DBUS_MESSAGE_TYPE_METHOD_RETURN);
uint32_t zero = 0;
assert(dbus_message_append_args(reply, DBUS_TYPE_UINT32, &zero, DBUS_TYPE_INVALID));
DBusMessageIter value;
dbus_message_iter_init(reply, &value);
process_fdo_setting(FDO_APPEARANCE_KEY, &value);
assert(glfw_has_system_color_theme() && notifications == 1 && received == GLFW_COLOR_SCHEME_NO_PREFERENCE);
dbus_message_unref(reply);
notifications = 0;
change_scheme(1);
assert(notifications == 1 && received == GLFW_COLOR_SCHEME_DARK);
change_scheme(2);
assert(notifications == 2 && received == GLFW_COLOR_SCHEME_LIGHT);
assert(appearance == GLFW_COLOR_SCHEME_LIGHT);
change_scheme(1);
assert(notifications == 3 && received == GLFW_COLOR_SCHEME_DARK);
change_scheme(1);
assert(notifications == 3);
change_scheme(0);
assert(notifications == 4 && received == GLFW_COLOR_SCHEME_NO_PREFERENCE);
_GLFWwindow window = {0};
_glfw.windowListHead = &window;
double factor;
bool bold;
assert(strcmp(glfw_current_system_font(&factor, &bold), "sans-serif 11") == 0 && factor == 1 && bold);
const char *font = "Ubuntu Sans Bold Italic 13";
change_setting(GNOME_WM_NAMESPACE, "titlebar-font", DBUS_TYPE_STRING, &font);
dbus_bool_t flag = false;
change_setting(GNOME_WM_NAMESPACE, "titlebar-uses-system-font", DBUS_TYPE_BOOLEAN, &flag);
assert(strcmp(glfw_current_system_font(&factor, &bold), font) == 0 && !bold);
flag = true;
change_setting(GNOME_WM_NAMESPACE, "titlebar-uses-system-font", DBUS_TYPE_BOOLEAN, &flag);
const char *interface = "Ubuntu Sans 12";
change_setting(GNOME_DESKTOP_NAMESPACE, "font-name", DBUS_TYPE_STRING, &interface);
assert(strcmp(glfw_current_system_font(&factor, &bold), interface) == 0 && bold);
double scale = 2.;
change_setting(GNOME_DESKTOP_NAMESPACE, "text-scaling-factor", DBUS_TYPE_DOUBLE, &scale);
assert(glfw_current_titlebar_text_scale() == 2.);
assert(glfw_current_titlebar_height() == 76);
const char *large = "Ubuntu Sans 32";
change_setting(GNOME_DESKTOP_NAMESPACE, "font-name", DBUS_TYPE_STRING, &large);
assert(glfw_current_titlebar_height() == 122);
change_setting(GNOME_DESKTOP_NAMESPACE, "font-name", DBUS_TYPE_STRING, &interface);
unsigned previous = redraws;
scale = NAN;
change_setting(GNOME_DESKTOP_NAMESPACE, "text-scaling-factor", DBUS_TYPE_DOUBLE, &scale);
scale = -1.;
change_setting(GNOME_DESKTOP_NAMESPACE, "text-scaling-factor", DBUS_TYPE_DOUBLE, &scale);
scale = 9.;
change_setting(GNOME_DESKTOP_NAMESPACE, "text-scaling-factor", DBUS_TYPE_DOUBLE, &scale);
assert(glfw_current_titlebar_text_scale() == 2. && redraws == previous);
const char *buttons = "close:maximize,minimize,close,appmenu";
change_setting(GNOME_WM_NAMESPACE, "button-layout", DBUS_TYPE_STRING, &buttons);
assert(button_layout.left_count == 1 && button_layout.left[0] == 1);
assert(button_layout.right_count == 2 && button_layout.right[0] == 2 && button_layout.right[1] == 3);
previous = redraws;
buttons = "close::maximize";
change_setting(GNOME_WM_NAMESPACE, "button-layout", DBUS_TYPE_STRING, &buttons);
assert(button_layout.left_count == 1 && redraws == previous);
buttons = ":";
change_setting(GNOME_WM_NAMESPACE, "button-layout", DBUS_TYPE_STRING, &buttons);
assert(button_layout.left_count == 0 && button_layout.right_count == 0);
const char *action = "minimize";
change_setting(GNOME_WM_NAMESPACE, "action-double-click-titlebar", DBUS_TYPE_STRING, &action);
assert(glfw_current_titlebar_action(0) == TITLEBAR_ACTION_MINIMIZE);
action = "none";
change_setting(GNOME_WM_NAMESPACE, "action-right-click-titlebar", DBUS_TYPE_STRING, &action);
assert(glfw_current_titlebar_action(2) == TITLEBAR_ACTION_NONE);
action = "menu";
change_setting(GNOME_WM_NAMESPACE, "action-middle-click-titlebar", DBUS_TYPE_STRING, &action);
assert(glfw_current_titlebar_action(1) == TITLEBAR_ACTION_MENU);
action = "lower";
change_setting(GNOME_WM_NAMESPACE, "action-middle-click-titlebar", DBUS_TYPE_STRING, &action);
assert(glfw_current_titlebar_action(1) == TITLEBAR_ACTION_NONE);
assert(redraws > 0);
puts("Desktop portal: appearance, font preferences, scale validation and button layout signals passed");
return 0;
}

View file

@ -1,146 +0,0 @@
#define _POSIX_C_SOURCE 200809L
/* Standalone renderer checks; see docs/wayland-gnome-csd.md. */
#include "../wl_client_side_decorations.c"
#include <assert.h>
_GLFWlibrary _glfw;
_GLFWwindow *
_glfwWindowForId(GLFWid id) {
(void)id;
abort();
}
static GLFWTitlebarButtonLayout layout = {.right = {3, 2, 1}, .right_count = 3};
static double text_scale = 1.;
const GLFWTitlebarButtonLayout *glfw_current_titlebar_button_layout(void) { return &layout; }
double glfw_current_titlebar_text_scale(void) { return text_scale; }
unsigned glfw_current_titlebar_height(void) { return (unsigned)ceil(38 * fmax(1, text_scale)); }
static bool theme_available = true;
bool glfw_has_system_color_theme(void) { return theme_available; }
static GLFWColorScheme scheme = GLFW_COLOR_SCHEME_DARK;
GLFWAPI GLFWColorScheme
glfwGetCurrentSystemColorTheme(bool query) {
(void)query;
return scheme;
}
int
main(void) {
_GLFWwindow w = {0};
w.id = _glfw.focusedWindowId = 1;
w.wl.wm_capabilities.maximize = w.wl.wm_capabilities.minimize = true;
csd_initialize_metrics(&w);
assert(w.wl.decorations.metrics.visible_titlebar_height == 38);
const double scales[] = {1, 1.25, 1.5, 2};
const int widths[] = {1, 12, 40, 72, 128, 800};
for (unsigned si = 0; si < sizeof(scales) / sizeof(*scales); si++)
for (unsigned wi = 0; wi < sizeof(widths) / sizeof(*widths); wi++)
for (int state = 0; state < 4; state++) {
double scale = scales[si];
w.wl.decorations.for_window_state.fscale = scale;
int width = (int)round(widths[wi] * scale), height = (int)round(38 * scale);
w.wl.decorations.titlebar.buffer.width = width;
w.wl.decorations.titlebar.buffer.height = height;
w.wl.current.toplevel_states = state == 1 ? TOPLEVEL_STATE_MAXIMIZED : 0;
_glfw.focusedWindowId = state == 2 ? 0 : 1;
scheme = state == 3 ? GLFW_COLOR_SCHEME_LIGHT : GLFW_COLOR_SCHEME_DARK;
size_t bytes = (size_t)width * height * 4;
uint8_t *data = malloc(bytes + 32);
assert(data);
memset(data, 0xab, bytes + 32);
render_titlebar_pixels(&w, data);
for (int i = 0; i < 32; i++) assert(data[bytes + i] == 0xab);
if (widths[wi] >= 128) {
assert(((uint32_t *)data)[(height / 2) * width] == (state == 3 ? 0xffebebeb : 0xff303030));
unsigned corner_alpha = A(((uint32_t *)data)[0]);
if (state == 1) assert(corner_alpha == 255);
else {
assert(corner_alpha > 0 && corner_alpha < 128);
size_t margin = (size_t)round(12 * scale);
assert(w.wl.decorations.shadow_tile.data[0] == 0);
unsigned expected = A(w.wl.decorations.shadow_tile.data[margin * w.wl.decorations.shadow_tile.stride + margin]);
if (state == 2) expected /= 2;
assert(corner_alpha == expected);
size_t stride = w.wl.decorations.shadow_tile.stride;
unsigned right = A(w.wl.decorations.shadow_tile.data[margin * stride + stride - margin - 1]);
if (state == 2) right /= 2;
assert(A(((uint32_t *)data)[width - 1]) == right);
}
assert(w.wl.decorations.close.width > 0);
assert(w.wl.decorations.close.left >= 0);
assert(w.wl.decorations.close.width == (int)round(36 * scale));
assert(w.wl.decorations.close.left - w.wl.decorations.maximize.left == (int)round(36 * scale));
}
if (wi == 5 && si == 0 && state == 0) {
FILE *f = fopen("/tmp/kitty-gnome-csd-preview.ppm", "wb");
assert(f);
fprintf(f, "P6\n%d %d\n255\n", width, height);
for (int i = 0; i < width * height; i++) {
uint32_t px = ((uint32_t *)data)[i];
unsigned char rgb[] = {R(px), G(px), B(px)};
fwrite(rgb, 1, 3, f);
}
fclose(f);
}
free(data);
}
w.wl.decorations.for_window_state.fscale = 1;
w.wl.decorations.titlebar.buffer.width = 128;
w.wl.decorations.titlebar.buffer.height = 38;
uint32_t custom_pixels[128 * 38];
theme_available = false;
scheme = GLFW_COLOR_SCHEME_NO_PREFERENCE;
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(custom_pixels[19 * 128] == 0xff303030);
theme_available = true;
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(custom_pixels[19 * 128] == 0xffebebeb);
const GLFWColorScheme transitions[] = {GLFW_COLOR_SCHEME_DARK, GLFW_COLOR_SCHEME_NO_PREFERENCE,
GLFW_COLOR_SCHEME_DARK, GLFW_COLOR_SCHEME_LIGHT, GLFW_COLOR_SCHEME_NO_PREFERENCE};
for (unsigned i = 0; i < sizeof(transitions) / sizeof(*transitions); i++) {
scheme = transitions[i];
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(custom_pixels[19 * 128] == (scheme == GLFW_COLOR_SCHEME_DARK ? 0xff303030 : 0xffebebeb));
}
w.wl.decorations.use_custom_titlebar_color = true;
const uint32_t custom_colors[] = {0x123456, 0xfafafa};
for (unsigned i = 0; i < sizeof(custom_colors) / sizeof(*custom_colors); i++) {
w.wl.decorations.titlebar_color = custom_colors[i];
for (int dark = 0; dark < 2; dark++) {
scheme = dark ? GLFW_COLOR_SCHEME_DARK : GLFW_COLOR_SCHEME_LIGHT;
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(custom_pixels[19 * 128] == (0xff000000 | custom_colors[i]));
}
}
w.wl.decorations.use_custom_titlebar_color = false;
w.wl.decorations.titlebar.buffer.width = 128;
w.wl.decorations.titlebar.buffer.height = 38;
layout = (GLFWTitlebarButtonLayout){.left = {1}, .right = {3, 2}, .left_count = 1, .right_count = 2};
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(w.wl.decorations.close.left == 6);
assert(w.wl.decorations.minimize.left == 50 && w.wl.decorations.maximize.left == 86);
layout = (GLFWTitlebarButtonLayout){0};
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(!w.wl.decorations.close.width && !w.wl.decorations.maximize.width && !w.wl.decorations.minimize.width);
layout = (GLFWTitlebarButtonLayout){.left = {1, 2, 3}, .left_count = 3};
w.wl.decorations.titlebar.buffer.width = 40;
render_titlebar_pixels(&w, (uint8_t *)custom_pixels);
assert(w.wl.decorations.close.width == 36);
assert(!w.wl.decorations.maximize.width && !w.wl.decorations.minimize.width);
text_scale = 2.;
csd_initialize_metrics(&w);
assert(w.wl.decorations.metrics.visible_titlebar_height == 76);
text_scale = .75;
csd_initialize_metrics(&w);
assert(w.wl.decorations.metrics.visible_titlebar_height == 38);
kernel_type *square = create_shadow_mask(84, 84, 12, 25, .7f, 384, 0);
kernel_type *rounded = create_shadow_mask(84, 84, 12, 25, .7f, 384, 12);
assert(square && rounded);
assert(rounded[12 * 84 + 12] < square[12 * 84 + 12]);
assert(rounded[70 * 84 + 12] == square[70 * 84 + 12]);
free(square);
free(rounded);
free(w.wl.decorations.shadow_tile.data);
w.wl.decorations.shadow_tile.data = NULL;
puts("GNOME CSD renderer: 96 scale/size/state combinations and corner-shadow continuity passed");
return 0;
}

View file

@ -3489,9 +3489,15 @@ opt(
long_text="""
The color of the kitty window's titlebar on Wayland systems with client
side window decorations such as GNOME. A value of :code:`system` means to use
the default system colors, a value of :code:`background` means to use the
the default system colors, following the desktop light/dark preference. If the
desktop has no preference, the titlebar follows the background color of the
currently active kitty window. A value of :code:`background` means to always use the
background color of the currently active kitty window and finally you can use an
arbitrary color, such as :code:`#12af59` or :code:`red`.
The titlebar font, its size, the placement of the buttons and the actions
performed when clicking on the titlebar are read from the GNOME desktop settings,
via the desktop portal.
""",
)