From d019b5ec713646e5b0d66b63879e059dcd628299 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Wed, 11 Mar 2026 19:39:30 +0100
Subject: [PATCH] Add 'xref-mouse-mode' minor mode

* doc/emacs/maintaining.texi (Looking Up Identifiers): Document
it.
* etc/NEWS (bindings): Mention it.
* etc/themes/newcomers-presets-theme.el (newcomers-presets): Add
it.
* lisp/progmodes/xref.el (xref-mouse-mode-map, xref-mouse-mode)
(global-xref-mouse-mode): Implement it.
---
 doc/emacs/maintaining.texi            |  7 ++++---
 etc/NEWS                              |  7 +++++++
 etc/themes/newcomers-presets-theme.el |  1 +
 lisp/progmodes/xref.el                | 28 +++++++++++++++++++++++++++
 4 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 38ecfa87e17..4aee5e1045d 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2675,10 +2675,11 @@ new frame for it.  The former is @w{@kbd{C-x 4 .}}
 (@code{xref-find-definitions-other-window}), and the latter is
 @w{@kbd{C-x 5 .}}  (@code{xref-find-definitions-other-frame}).
 
+@findex xref-mouse-mode
   The command @code{xref-find-definitions-at-mouse} works like
-@code{xref-find-definitions}, but it looks for the identifier name at
-or around the place of a mouse event.  This command is intended to be
-bound to a mouse event, such as @kbd{C-M-mouse-1}, for example.
+@code{xref-find-definitions}, but it looks for the identifier name at or
+around the place of a mouse event.  The @code{xref-mouse-mode} minor
+mode binds the command to @kbd{C-mouse-1}.
 
 @kindex C-M-.
 @findex xref-find-apropos
diff --git a/etc/NEWS b/etc/NEWS
index b7a4809d488..6e57adcd052 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3164,6 +3164,13 @@ destination window is chosen using 'display-buffer-alist'.  Example:
                                    display-buffer-use-some-window)
                                   (some-window . mru))))
 
++++
+*** New minor mode 'xref-mouse-mode'.
+This minor mode binds 'xref-find-definitions-at-mouse' to
+'C-<down-mouse-1>', allowing you to "control click" to jump to a
+definition, following the convention from other editors.  The global
+minor mode 'global-xref-mouse-mode' will enable this in all buffers.
+
 ** Revert
 
 +++
diff --git a/etc/themes/newcomers-presets-theme.el b/etc/themes/newcomers-presets-theme.el
index aabf47af608..542c424dec8 100644
--- a/etc/themes/newcomers-presets-theme.el
+++ b/etc/themes/newcomers-presets-theme.el
@@ -105,6 +105,7 @@ This minor mode will enable and disable the theme on startup."
  '(mouse-drag-and-drop-region t)
  '(mouse-drag-and-drop-region-cross-program t)
  '(mouse-drag-mode-line-buffer t)
+ '(global-xref-mouse-mode t)
 
 ;;;; Persistence-related options
  '(savehist-mode t)
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 1e51b23eaff..f4d2c499d7a 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -1731,6 +1731,34 @@ This command is intended to be bound to a mouse event."
           (xref-find-references identifier))
       (user-error "No identifier here"))))
 
+(defvar-keymap xref-mouse-mode-map
+  ;; Using "Control-Click" has been popularized TextMate and it's
+  ;; descendants (Sublime, Atom, VSCode) and even other traditions such
+  ;; as Eclipse or the IntelliJ editor suite.
+  ;;
+  ;; TODO: Add some kind of hovering indication that a identifier under
+  ;; the mouse cursor has a definition we could jump to.
+  "C-<down-mouse-1>" #'xref-find-definitions-at-mouse
+  "C-<mouse-1>" #'xref-find-definitions-at-mouse
+  "C-<drag-mouse-1>" #'xref-find-definitions-at-mouse)
+
+;;;###autoload
+(define-minor-mode xref-mouse-mode
+  "Minor mode to bind Xref commands invoked using the mouse.
+See `global-xref-mouse-mode' if you want to enable this minor mode in
+all buffers."
+  :version "31.1")
+
+;;;###autoload
+(define-globalized-minor-mode global-xref-mouse-mode
+  xref-mouse-mode xref-mouse-mode
+  :version "31.1")
+
+;; ;;;##autoload
+;; (add-to-list
+;;  'emulation-mode-map-alists             ;since we are "emulating" other conventions
+;;  `((xref-mouse-mode . ,xref-mouse-mode-map)))
+
 (declare-function apropos-parse-pattern "apropos" (pattern &optional do-all))
 
 ;;;###autoload