Fix link hover regressions identified in review

Refresh hover feedback only in the hovered pane when modifier changes alter
whether a single-click link action matches. Preserve resize and drag cursors
and keep OSC 22 pointer updates independent of modifier handling.

Compute link modifier masks while finalizing mouse mappings, clarify the
documentation, and cover the reported regressions with mock pointer events.
This commit is contained in:
Zhizhen He 2026-10-23 12:59:35 +08:00
parent e6561b6337
commit 4e9ff82c77
No known key found for this signature in database
GPG key ID: B5A215D74FCFD6A7
10 changed files with 180 additions and 39 deletions

View file

@ -234,11 +234,6 @@ Detailed list of changes
- Remote control: Fix a crash when using damaged images with
:code:`set-window-logo` or :code:`set-background-image` (:pull:`10715`)
- Show the hand pointer and hover highlighting over links only when the pressed
modifiers match a configured mouse action for opening the link. Update both
immediately when modifiers are pressed or released, even without moving the
mouse.
- Transfer kitten: When receiving files, replace existing symbolic and hard
links at the destination instead of overwriting the files they point to.
Files are now written to a temporary file and renamed into place, so an
@ -251,6 +246,11 @@ Detailed list of changes
status bars, file trees, etc. Create them with :code:`launch --type=window-dock`
or :code:`launch --type=tab-dock`, see :ref:`docks`
- Show the hand pointer and hover highlighting over links only when the pressed
modifiers match a configured mouse action for opening the link with a single
click. Update both immediately when modifiers are pressed or released, even
without moving the mouse.
- A new option :opt:`restore_session_after_logout` to save the state of
every kitty instance, including the scrollback of every window, when logging
out, restarting or shutting down the computer and restore it the next time

View file

@ -121,6 +121,9 @@ def finalize_keys(opts: Options, accumulate_bad_lines: list[BadLine] | None = No
def finalize_mouse_mappings(opts: Options, accumulate_bad_lines: list[BadLine] | None = None) -> None:
from .fast_data_types import GLFW_MOUSE_BUTTON_LAST
from .keys import mod_mask
defns: list[MouseMapping] = []
for d in opts.mouse_map:
if d is None: # clear_all_mouse_actions
@ -141,15 +144,9 @@ def finalize_mouse_mappings(opts: Options, accumulate_bad_lines: list[BadLine] |
else:
mousemap.pop(defn.trigger, None)
opts.mousemap = mousemap
def mouse_url_modifiers(opts: Options) -> tuple[int, int]:
from .fast_data_types import GLFW_MOUSE_BUTTON_LAST
from .keys import mod_mask
modifiers = [0, 0]
for event, definition in opts.mousemap.items():
if not 0 <= event.button <= GLFW_MOUSE_BUTTON_LAST or event.mods & ~mod_mask:
opts.url_mappings = {False: 0, True: 0}
for event, definition in mousemap.items():
if not 0 <= event.button <= GLFW_MOUSE_BUTTON_LAST or event.mods & ~mod_mask or event.repeat_count not in (-2, -1, 1):
continue
try:
actions = opts.alias_map.resolve_aliases(definition, MapType.MOUSE_MAP)
@ -157,8 +154,7 @@ def mouse_url_modifiers(opts: Options) -> tuple[int, int]:
log_error(f'Ignoring mouse_map with invalid action: {definition}. Error: {err}')
continue
if any(a.func in ('mouse_click_url', 'mouse_click_url_or_select') or (a.func == 'mouse_handle_click' and 'link' in a.args) for a in actions):
modifiers[event.grabbed] |= 1 << event.mods
return modifiers[0], modifiers[1]
opts.url_mappings[event.grabbed] |= 1 << event.mods
def parse_config(

View file

@ -607,7 +607,7 @@ key_callback(GLFWwindow *w, GLFWkeyevent *ev) {
global_state.callback_os_window->user_is_idle = false;
global_state.callback_os_window->shader_anim_event_registry |= (1u << SHADER_ANIM_EVENT_USER_ACTIVITY);
if (is_window_ready_for_callbacks()) {
if ((old_mods ^ ev->mods) & ~GLFW_LOCK_MASK) update_mouse_pointer_shape();
update_link_hover_for_modifiers(old_mods, ev->mods);
if (!ev->fake_event_on_focus_change) on_key_input(ev);
}
global_state.callback_os_window = NULL;
@ -1615,7 +1615,8 @@ set_glfw_mouse_pointer_shape_in_window(GLFWwindow *w, MouseShape type) {
void
set_mouse_cursor(MouseShape type) {
if (global_state.callback_os_window) {
// Headless mock OS windows have no native cursor.
if (global_state.callback_os_window && global_state.callback_os_window->handle) {
GLFWwindow *w = (GLFWwindow *)global_state.callback_os_window->handle;
set_glfw_mouse_pointer_shape_in_window(w, type);
}

View file

@ -1176,9 +1176,6 @@ focus_in_event(void) {
void
update_mouse_pointer_shape(void) {
if (global_state.redirect_mouse_handling || global_state.active_drag_in_window || global_state.tracked_drag_in_window ||
global_state.tab_being_dragged.id || global_state.window_being_dragged.id || global_state.active_drag_resize)
return;
mouse_cursor_shape = TEXT_POINTER;
MouseRegion r = mouse_region(false, true);
if (r.in_tab_bar) {
@ -1189,12 +1186,7 @@ update_mouse_pointer_shape(void) {
if (handle_scrollbar_mouse(r.window, -1, MOVE, 0)) {
mouse_cursor_shape = scrollbar_drag_mouse_cursor;
} else if (r.window->render_data.screen) {
screen_mark_url(r.window->render_data.screen, 0, 0, 0, 0);
set_mouse_cursor_for_screen(r.window->render_data.screen);
bool mouse_cell_changed, cell_half_changed;
if (OPT(detect_urls) && set_mouse_position(r.window, &mouse_cell_changed, &cell_half_changed)) {
detect_url(r.window->render_data.screen, r.window->mouse_pos.cell_x, r.window->mouse_pos.cell_y, global_state.mods_at_last_key_or_button_event);
}
}
}
set_mouse_cursor(mouse_cursor_shape);
@ -1206,6 +1198,30 @@ leave_event(int modifiers) {
set_currently_hovered_window(0, modifiers, false);
}
bool
update_link_hover_for_modifiers(int old_mods, int new_mods) {
old_mods &= MOUSE_MAPPING_MODS_MASK;
new_mods &= MOUSE_MAPPING_MODS_MASK;
OSWindow *osw = global_state.callback_os_window;
if (old_mods == new_mods || !OPT(detect_urls) || !osw || !osw->num_tabs || !global_state.mouse_hover_in_window || global_state.redirect_mouse_handling ||
global_state.active_drag_in_window || global_state.tracked_drag_in_window || global_state.tab_being_dragged.id ||
global_state.window_being_dragged.id || global_state.active_drag_resize)
return false;
Tab *tab = osw->tabs + osw->active_tab;
for (unsigned i = 0; i < tab->num_windows; i++) {
Window *w = tab->windows + i;
if (w->id != global_state.mouse_hover_in_window) continue;
Screen *screen = w->render_data.screen;
if (!w->visible || !screen || w->scrollbar.is_hovering || w->scrollbar.is_dragging) return false;
const uint64_t mappings = OPT(url_mappings)[screen->modes.mouse_tracking_mode != NO_TRACKING];
if (((mappings >> old_mods) & 1) == ((mappings >> new_mods) & 1)) return false;
detect_url(screen, w->mouse_pos.cell_x, w->mouse_pos.cell_y, new_mods);
set_mouse_cursor(mouse_cursor_shape);
return true;
}
return false;
}
void
enter_event(int modifiers, bool cursor_moved) {
#ifdef __APPLE__
@ -1969,6 +1985,64 @@ send_mock_mouse_event_to_window(PyObject *self UNUSED, PyObject *args) {
return PyLong_FromLong(mouse_cursor_shape);
}
static PyObject *
update_mock_pointer(PyObject *self UNUSED, PyObject *args) {
PyObject *capsule;
int old_mods, new_mods, inside = 1;
unsigned drag = 0, border = 0;
const char *pointer_shape = NULL;
if (!PyArg_ParseTuple(args, "O!ii|pIIs", &PyCapsule_Type, &capsule, &old_mods, &new_mods, &inside, &drag, &border, &pointer_shape)) return NULL;
Window *w = PyCapsule_GetPointer(capsule, "Window");
if (!w) return NULL;
Screen *screen = w->render_data.screen;
GlobalState saved = global_state;
MouseShape saved_shape = mouse_cursor_shape;
Window windows[] = {*w, *w};
windows[1].id++;
windows[0].render_data.geometry = (WindowGeometry){.right = screen->columns * 10, .bottom = screen->lines * 20};
windows[1].render_data.geometry = windows[0].render_data.geometry;
BorderRect rect = {.border_type = (int)w->id, .horizontal = border == 2};
rect.px.left = (unsigned)w->mouse_pos.global_x;
rect.px.right = rect.px.left + 1;
rect.px.top = (unsigned)w->mouse_pos.global_y;
rect.px.bottom = rect.px.top + 1;
Tab tab = {.windows = windows, .num_windows = border ? 2 : 1};
tab.border_rects.rect_buf = &rect;
tab.border_rects.num_border_rects = border ? 1 : 0;
struct {
FONTS_DATA_HEAD
} fonts = {.logical_dpi_x = 72, .logical_dpi_y = 72, .fcm = {.cell_width = 10, .cell_height = 20}};
OSWindow osw = {
.tabs = &tab,
.num_tabs = 1,
.has_too_few_tabs = true,
.fonts_data = (FONTS_DATA_HANDLE)&fonts,
.viewport_width = screen->columns * 10,
.viewport_height = screen->lines * 20,
.mouse_x = w->mouse_pos.global_x,
.mouse_y = w->mouse_pos.global_y};
global_state.callback_os_window = &osw;
global_state.mouse_hover_in_window = global_state.active_drag_in_window = global_state.tracked_drag_in_window = global_state.active_drag_resize = 0;
global_state.tab_being_dragged.id = global_state.window_being_dragged.id = 0;
global_state.redirect_mouse_handling = false;
global_state.mods_at_last_key_or_button_event = old_mods;
mouse_event(-1, old_mods, -1);
if (!inside) leave_event(old_mods);
if (drag == 1) global_state.active_drag_in_window = w->id;
else if (drag == 2) global_state.tracked_drag_in_window = w->id;
global_state.mods_at_last_key_or_button_event = new_mods;
bool updated = false;
if (pointer_shape) {
RAII_PyObject(ret, PyObject_CallMethod((PyObject *)screen, "change_pointer_shape", "ss", "=", pointer_shape));
if (ret) update_mouse_pointer_shape();
} else updated = update_link_hover_for_modifiers(old_mods, new_mods);
MouseShape result = mouse_cursor_shape;
global_state = saved;
mouse_cursor_shape = saved_shape;
if (PyErr_Occurred()) return NULL;
return Py_BuildValue("(iO)", result, updated ? Py_True : Py_False);
}
static PyObject *
test_scale_scroll(PyObject *self UNUSED, PyObject *args) {
PyObject *values;
@ -2043,6 +2117,7 @@ static PyMethodDef module_methods[] = {
METHODB(test_scale_scroll, METH_VARARGS),
METHODB(test_mapped_scroll_steps, METH_VARARGS),
METHODB(send_mock_mouse_event_to_window, METH_VARARGS),
METHODB(update_mock_pointer, METH_VARARGS),
METHODB(send_mock_scroll_event_to_window, METH_VARARGS),
METHODB(mock_mouse_selection, METH_VARARGS),
{NULL, NULL, 0, NULL} /* Sentinel */

View file

@ -17,7 +17,7 @@ definition = Definition(
{'keyboard_modes': 'KeyboardModeMap', 'alias_map': 'AliasMap'},
['KeyDefinition', 'KeyMapOptions', 'kitty.fast_data_types.SingleKey'],
),
Action('mouse_map', 'parse_mouse_map', {'mousemap': 'MouseMap'}, ['MouseMapping']),
Action('mouse_map', 'parse_mouse_map', {'mousemap': 'MouseMap', 'url_mappings': 'URLMappings'}, ['MouseMapping']),
has_color_table=True,
)
definition.add_deprecation('deprecated_hide_window_decorations_aliases', 'x11_hide_window_decorations', 'macos_hide_titlebar')
@ -1226,11 +1226,6 @@ Mouse buttons can be mapped to perform arbitrary actions. The syntax is:
mouse_map button-name event-type modes action
The mouse pointer changes to a hand and links are highlighted on hover only when
the current keyboard modifiers and grabbed/ungrabbed mode match a mouse mapping
that opens the link. Both update when modifiers are pressed or released, even
if the mouse does not move.
Where :code:`button-name` is one of :code:`left`, :code:`middle`, :code:`right`,
:code:`b1` ... :code:`b8`, :code:`wheel_up`, :code:`wheel_down`,
:code:`wheel_left`, :code:`wheel_right` with added keyboard modifiers. For example: :code:`ctrl+shift+left` refers to holding the
@ -1275,6 +1270,12 @@ grabbed by the program running in the terminal, or not. The values are
mouse events. Note that the click and double click events have a delay of
:opt:`click_interval` to disambiguate from double and triple presses.
The mouse pointer changes to a hand and links are highlighted on hover only when
the current keyboard modifiers and grabbed/ungrabbed mode match a mouse mapping
that opens the link on a single :code:`press`, :code:`release` or :code:`click`.
Both update when modifiers are pressed or released, even if the mouse does not
move. Mappings that require a double or triple click do not enable hover feedback.
You can run kitty with the :option:`kitty --debug-input` command line option
to see mouse events. See the builtin actions below to get a sense of what is
possible.

View file

@ -12,7 +12,7 @@ from kitty.fonts import FontSpec
import kitty.fonts
from kitty.options.utils import (
AliasMap, KeyDefinition, KeyFallbackType, KeyMapOptions, KeyboardModeMap, MouseHideWait, MouseMap,
MouseMapping, NotifyOnCmdFinish, TabBarMarginHeight
MouseMapping, NotifyOnCmdFinish, TabBarMarginHeight, URLMappings
)
import kitty.options.utils
from kitty.types import FloatEdges
@ -762,6 +762,7 @@ class Options:
alias_map: AliasMap = AliasMap()
mouse_map: list[kitty.options.utils.MouseMapping] = []
mousemap: MouseMap = {}
url_mappings: URLMappings = {}
color_table: "array[int]" = array("L", (
0x000000, 0xcc0403, 0x19cb00, 0xcecb00, 0x0d73cc, 0xcb1ed1, 0x0dcdcd, 0xdddddd,
0x767676, 0xf2201f, 0x23fd00, 0xfffd00, 0x1a8fff, 0xfd28ff, 0x14ffff, 0xffffff,

View file

@ -47,6 +47,7 @@ from kitty.utils import expandvars, log_error, resolve_abs_or_config_path, shlex
KeyMap = dict[SingleKey, list['KeyDefinition']]
MouseMap = dict[MouseEvent, str]
URLMappings = dict[bool, int]
KeySequence = tuple[SingleKey, ...]
MINIMUM_FONT_SIZE = 4
# Zooming is limited to a multiple of the configured font size, or to this

View file

@ -382,7 +382,11 @@ initialize_window(Window *w, PyObject *title, bool init_gpu_resources) {
if (PyErr_Occurred()) PyErr_Print();
}
if (init_gpu_resources) create_gpu_resources_for_window(w);
else { w->render_data.vao_idx = w->window_title_render_data.vao_idx = -1; }
else {
// Mock windows have no graphics context. Neither VAO may be deleted when
// the mock window is destroyed by the mouse regression tests.
w->render_data.vao_idx = w->window_title_render_data.vao_idx = -1;
}
}
static id_type
@ -1148,12 +1152,11 @@ PYWRAP1(set_options) {
global_state.debug_font_fallback = debug_font_fallback ? true : false;
if (!convert_opts_from_python_opts(opts, &global_state.opts)) return NULL;
if (!set_wheel_mappings(opts, &global_state.opts)) return NULL;
RAII_PyObject(config, PyImport_ImportModule("kitty.config"));
if (!config) return NULL;
RAII_PyObject(url_modifiers, PyObject_CallMethod(config, "mouse_url_modifiers", "O", opts));
if (!url_modifiers) return NULL;
RAII_PyObject(url_mappings, PyObject_GetAttrString(opts, "url_mappings"));
if (!url_mappings) return NULL;
for (size_t i = 0; i < arraysz(global_state.opts.url_mappings); i++) {
global_state.opts.url_mappings[i] = PyLong_AsUnsignedLongLong(PyTuple_GET_ITEM(url_modifiers, i));
PyObject *mask = PyDict_GetItem(url_mappings, i ? Py_True : Py_False);
global_state.opts.url_mappings[i] = mask ? PyLong_AsUnsignedLongLong(mask) : 0;
if (PyErr_Occurred()) return NULL;
}
if (!set_vertical_tab_bar_padding(opts, &global_state.opts)) return NULL;

View file

@ -851,6 +851,7 @@ void update_menu_bar_title(PyObject *title UNUSED);
void change_live_resize_state(OSWindow *, bool);
bool render_os_window(OSWindow *w, monotonic_t now, bool scan_for_animated_images);
void update_mouse_pointer_shape(void);
bool update_link_hover_for_modifiers(int old_mods, int new_mods);
void adjust_window_size_for_csd(OSWindow *w, int width, int height, int *adjusted_width, int *adjusted_height);
void dispatch_buffered_keys(Window *w);
void free_buffered_keys(Window *w);

View file

@ -10,6 +10,7 @@ from kitty.fast_data_types import (
GLFW_MOD_CAPS_LOCK,
GLFW_MOD_CONTROL,
GLFW_MOD_SHIFT,
GLFW_MOD_SUPER,
GLFW_MOUSE_BUTTON_LEFT,
GLFW_MOUSE_BUTTON_RIGHT,
MOUSE_SELECTION_WORD_AND_LINE_FROM_POINT,
@ -18,6 +19,7 @@ from kitty.fast_data_types import (
send_mock_mouse_event_to_window,
send_mock_scroll_event_to_window,
set_options,
update_mock_pointer,
)
from .base import BaseTest, parse_bytes
@ -97,6 +99,66 @@ class TestMouse(BaseTest):
configure('mouse_map left click ungrabbed mouse_click_url', 'mouse_map left click ungrabbed')
check(0, False)
for event in ('press', 'release', 'click'):
configure(f'mouse_map cmd+left {event} ungrabbed mouse_handle_click link')
check(GLFW_MOD_SUPER, True)
check(0, False)
for event in ('doublepress', 'triplepress', 'doubleclick'):
configure(f'mouse_map left {event} ungrabbed mouse_click_url')
check(0, False)
def test_link_hover_key_events(self):
s = self.create_screen(cols=60)
s.draw('https://example.invalid/')
w = create_mock_window(s)
link_shape = send_mouse_event(w, x=2)
mods = GLFW_MOD_CONTROL | GLFW_MOD_SHIFT
set_options(
load_config(
overrides=(
'clear_all_mouse_actions yes',
'mouse_map ctrl+shift+left release grabbed,ungrabbed mouse_handle_click link',
'mouse_map cmd+left release grabbed,ungrabbed mouse_handle_click link',
)
)
)
for tracking in (False, True):
parse_bytes(s, b'\x1b[?1000h' if tracking else b'\x1b[?1000l')
normal_shape = send_mouse_event(w, x=50)
send_mouse_event(w, x=2)
for held in (mods, GLFW_MOD_SUPER):
for old, new, highlighted in ((0, held, True), (held, 0, False)):
self.ae(update_mock_pointer(w, old, new), (link_shape if highlighted else normal_shape, True))
self.ae(bool(''.join(s.text_for_marked_url())), highlighted)
self.ae(update_mock_pointer(w, 0, held, False)[1], False)
self.ae(''.join(s.text_for_marked_url()), '')
for old, new in ((0, GLFW_MOD_SHIFT), (mods, GLFW_MOD_SUPER), (mods, mods | GLFW_MOD_CAPS_LOCK)):
self.ae(update_mock_pointer(w, old, new)[1], False)
for drag in (1, 2):
self.ae(update_mock_pointer(w, 0, mods, True, drag)[1], False)
def test_link_hover_preserves_border_cursor(self):
s = self.create_screen(cols=60)
s.draw('https://example.invalid/')
w = create_mock_window(s)
send_mouse_event(w, x=2)
mods = GLFW_MOD_CONTROL | GLFW_MOD_SHIFT
for border in (1, 2):
shape, updated = update_mock_pointer(w, 0, 0, True, 0, border)
self.ae(updated, False)
self.ae(update_mock_pointer(w, 0, mods, True, 0, border), (shape, False))
def test_pointer_shape_during_mouse_drag(self):
s = self.create_screen(cols=60)
parse_bytes(s, b'\x1b[?1000h')
w = create_mock_window(s)
for drag in (1, 2):
for name in ('grabbing', 'ew-resize'):
s.change_pointer_shape('=', name)
expected = send_mouse_event(w, x=2)
s.change_pointer_shape('=', 'text')
self.ae(update_mock_pointer(w, 0, 0, True, drag, 0, name)[0], expected)
def test_mouse_selection(self):
s = self.create_screen(options=dict(rectangle_select_modifiers=GLFW_MOD_ALT | GLFW_MOD_CONTROL))
w = create_mock_window(s)