From: Juri Linkov Date: Wed, 15 Sep 2021 16:00:56 +0000 (+0300) Subject: Add docstrings to context menu functions, and add middle-separator X-Git-Tag: emacs-28.0.90~947 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=231a29f36333d10b7122bb9e25da4db8cb03b73d;p=emacs.git Add docstrings to context menu functions, and add middle-separator * lisp/mouse.el (context-menu-functions): Add context-menu-middle-separator to default values. (context-menu-middle-separator): New function. * lisp/replace.el (occur-context-menu): Use middle-separator. * lisp/progmodes/elisp-mode.el (elisp-context-menu): * lisp/progmodes/prog-mode.el (prog-context-menu): Use middle-separator and reorder menu items correspondingly. --- diff --git a/lisp/dired.el b/lisp/dired.el index 1ed83cb95a7..9978d027a98 100644 --- a/lisp/dired.el +++ b/lisp/dired.el @@ -2194,6 +2194,7 @@ Do so according to the former subdir alist OLD-SUBDIR-ALIST." :help "Delete image tag from current or marked files"])) (defun dired-context-menu (menu click) + "Populate MENU with Dired mode commands at CLICK." (when (mouse-posn-property (event-start click) 'dired-filename) (define-key menu [dired-separator] menu-bar-separator) (let ((easy-menu (make-sparse-keymap "Immediate"))) diff --git a/lisp/help-mode.el b/lisp/help-mode.el index d341b4c9e4a..d2066a05f7d 100644 --- a/lisp/help-mode.el +++ b/lisp/help-mode.el @@ -71,6 +71,7 @@ :help "Customize variable or face"])) (defun help-mode-context-menu (menu click) + "Populate MENU with Help mode commands at CLICK." (define-key menu [help-mode-separator] menu-bar-separator) (let ((easy-menu (make-sparse-keymap "Help-Mode"))) (easy-menu-define nil easy-menu nil diff --git a/lisp/info.el b/lisp/info.el index b861fff744c..8c08eaec3c8 100644 --- a/lisp/info.el +++ b/lisp/info.el @@ -4152,6 +4152,7 @@ If FORK is non-nil, it is passed to `Info-goto-node'." ["Exit" quit-window :help "Stop reading Info"])) (defun Info-context-menu (menu click) + "Populate MENU with Info commands at CLICK." (define-key menu [Info-separator] menu-bar-separator) (let ((easy-menu (make-sparse-keymap "Info"))) (easy-menu-define nil easy-menu nil diff --git a/lisp/mouse.el b/lisp/mouse.el index c107322815a..f33a73f03ff 100644 --- a/lisp/mouse.el +++ b/lisp/mouse.el @@ -281,6 +281,7 @@ not it is actually displayed." (defcustom context-menu-functions '(context-menu-undo context-menu-region + context-menu-middle-separator context-menu-local context-menu-minor) "List of functions that produce the contents of the context menu. @@ -305,11 +306,19 @@ and should return the same menu with changes such as added new menu items." :version "28.1") (defun context-menu-map (&optional click) - "Return composite menu map." + "Return menu map constructed for context near mouse CLICK. +The menu is populated by calling functions from `context-menu-functions'. +Each function receives the menu and the mouse click event +and returns the same menu after adding own menu items to the composite menu. +When there is a text property `context-menu-function' at CLICK, +it overrides all functions from `context-menu-functions'. +At the end, it's possible to modify the final menu by specifying +the function `context-menu-filter-function'." (let* ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t))) (click (or click last-input-event)) (fun (mouse-posn-property (event-start click) 'context-menu-function))) + (if (functionp fun) (setq menu (funcall fun menu click)) (run-hook-wrapped 'context-menu-functions @@ -329,8 +338,14 @@ and should return the same menu with changes such as added new menu items." (setq menu (funcall context-menu-filter-function menu click))) menu)) +(defun context-menu-middle-separator (menu _click) + "Add separator to the middle of the context menu. +Some context functions add menu items below the separator." + (define-key-after menu [middle-separator] menu-bar-separator) + menu) + (defun context-menu-toolbar (menu _click) - "Tool bar menu items." + "Populate MENU with submenus from the tool bar." (run-hooks 'activate-menubar-hook 'menu-bar-update-hook) (define-key-after menu [separator-toolbar] menu-bar-separator) (map-keymap (lambda (key binding) @@ -341,7 +356,7 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-global (menu _click) - "Global submenus." + "Populate MENU with submenus from the global menu." (run-hooks 'activate-menubar-hook 'menu-bar-update-hook) (define-key-after menu [separator-global] menu-bar-separator) (map-keymap (lambda (key binding) @@ -352,7 +367,7 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-local (menu _click) - "Major mode submenus." + "Populate MENU with submenus provided by major mode." (run-hooks 'activate-menubar-hook 'menu-bar-update-hook) (define-key-after menu [separator-local] menu-bar-separator) (let ((keymap (local-key-binding [menu-bar]))) @@ -365,7 +380,7 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-minor (menu _click) - "Minor modes submenus." + "Populate MENU with submenus provided by minor modes." (run-hooks 'activate-menubar-hook 'menu-bar-update-hook) (define-key-after menu [separator-minor] menu-bar-separator) (dolist (mode (reverse (minor-mode-key-binding [menu-bar]))) @@ -378,7 +393,7 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-buffers (menu _click) - "Submenus with buffers." + "Populate MENU with the buffer submenus to buffer switching." (run-hooks 'activate-menubar-hook 'menu-bar-update-hook) (define-key-after menu [separator-buffers] menu-bar-separator) (map-keymap (lambda (key binding) @@ -389,13 +404,13 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-vc (menu _click) - "Version Control menu." + "Populate MENU with Version Control commands." (define-key-after menu [separator-vc] menu-bar-separator) (define-key-after menu [vc-menu] vc-menu-entry) menu) (defun context-menu-undo (menu _click) - "Undo menu." + "Populate MENU with undo commands." (define-key-after menu [separator-undo] menu-bar-separator) (when (and (not buffer-read-only) (not (eq t buffer-undo-list)) @@ -413,7 +428,7 @@ and should return the same menu with changes such as added new menu items." menu) (defun context-menu-region (menu _click) - "Region commands menu." + "Populate MENU with region commands." (define-key-after menu [separator-region] menu-bar-separator) (when (and mark-active (not buffer-read-only)) (define-key-after menu [cut] @@ -451,26 +466,27 @@ and should return the same menu with changes such as added new menu items." (define-key-after menu [clear] '(menu-item "Clear" delete-active-region :help - "Delete the text in region between mark and current position"))) + "Delete text in region between mark and current position"))) (define-key-after menu [mark-whole-buffer] '(menu-item "Select All" mark-whole-buffer :help "Mark the whole buffer for a subsequent cut/copy")) menu) (defun context-menu-ffap (menu click) - "File at point menu." + "Populate MENU with commands that find file at point." (save-excursion (mouse-set-point click) (when (ffap-guess-file-name-at-point) (define-key menu [ffap-separator] menu-bar-separator) (define-key menu [ffap-at-mouse] '(menu-item "Find File or URL" ffap-at-mouse - :help "Find file or URL guessed from text around mouse click")))) + :help "Find file or URL from text around mouse click")))) menu) (defvar context-menu-entry `(menu-item ,(purecopy "Context Menu") ignore - :filter (lambda (_) (context-menu-map)))) + :filter (lambda (_) (context-menu-map))) + "Menu item that creates the context menu and can be bound to a mouse key.") (defvar context-menu-mode-map (let ((map (make-sparse-keymap))) diff --git a/lisp/net/dictionary.el b/lisp/net/dictionary.el index 9353b4d3759..4947caba699 100644 --- a/lisp/net/dictionary.el +++ b/lisp/net/dictionary.el @@ -1376,7 +1376,7 @@ any buffer where (dictionary-tooltip-mode 1) has been called." (dictionary-search word))) (defun context-menu-dictionary (menu click) - "Dictionary context menu." + "Populate MENU with dictionary commands at CLICK." (when (thing-at-mouse click 'word) (define-key menu [dictionary-separator] menu-bar-separator) (define-key menu [dictionary-search-word-at-mouse] diff --git a/lisp/net/eww.el b/lisp/net/eww.el index 16a13bbaaee..28569eeeb10 100644 --- a/lisp/net/eww.el +++ b/lisp/net/eww.el @@ -1027,6 +1027,7 @@ the like." map)) (defun eww-context-menu (menu click) + "Populate MENU with eww commands at CLICK." (define-key menu [eww-separator] menu-bar-separator) (let ((easy-menu (make-sparse-keymap "Eww"))) (easy-menu-define nil easy-menu nil diff --git a/lisp/net/goto-addr.el b/lisp/net/goto-addr.el index 97230f42fe8..78f6f3d915b 100644 --- a/lisp/net/goto-addr.el +++ b/lisp/net/goto-addr.el @@ -125,6 +125,7 @@ will have no effect.") "Keymap to hold goto-addr's mouse key defs under highlighted URLs.") (defun goto-address-context-menu (menu click) + "Populate MENU with goto-address commands at CLICK." (when (mouse-posn-property (event-start click) 'goto-address) (define-key menu [goto-address-separator] menu-bar-separator) (define-key menu [goto-address-at-mouse] diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index f71718bed52..55325ef488b 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -154,23 +154,24 @@ All commands in `lisp-mode-shared-map' are inherited by this map.") :selected (bound-and-true-p eldoc-mode)])) (defun elisp-context-menu (menu click) + "Populate MENU with symbol help commands at CLICK." (when (thing-at-mouse click 'symbol) (define-key-after menu [elisp-separator] menu-bar-separator - 'mark-whole-buffer) + 'middle-separator) + (define-key-after menu [info-lookup-symbol] + '(menu-item "Look up Symbol" + (lambda (click) (interactive "e") + (info-lookup-symbol + (intern (thing-at-mouse click 'symbol t)))) + :help "Display definition in relevant manual") + 'elisp-separator) (define-key-after menu [describe-symbol] '(menu-item "Describe Symbol" (lambda (click) (interactive "e") (describe-symbol (intern (thing-at-mouse click 'symbol t)))) :help "Display the full documentation of symbol") - 'elisp-separator) - (define-key-after menu [info-lookup-symbol] - '(menu-item "Lookup Symbol" - (lambda (click) (interactive "e") - (info-lookup-symbol - (intern (thing-at-mouse click 'symbol t)))) - :help "Display definition in relevant manual") - 'describe-symbol)) + 'elisp-separator)) menu) (defun emacs-lisp-byte-compile () diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el index bd2c6536388..88d55a647c8 100644 --- a/lisp/progmodes/prog-mode.el +++ b/lisp/progmodes/prog-mode.el @@ -44,30 +44,31 @@ prettify-symbols-mode)) (defun prog-context-menu (menu click) + "Populate MENU with xref commands at CLICK." (require 'xref) (define-key-after menu [prog-separator] menu-bar-separator - 'mark-whole-buffer) + 'middle-separator) + (when (not (xref-marker-stack-empty-p)) + (define-key-after menu [xref-pop] + '(menu-item "Back Definition" xref-pop-marker-stack + :help "Back to the position of the last search") + 'prog-separator)) (when (save-excursion (mouse-set-point click) (xref-backend-identifier-at-point (xref-find-backend))) - (define-key-after menu [xref-find-def] - '(menu-item "Find Definition" xref-find-definitions-at-mouse - :help "Find definition of identifier") + (define-key-after menu [xref-find-ref] + '(menu-item "Find References" xref-find-references-at-mouse + :help "Find references to identifier") 'prog-separator)) (when (save-excursion (mouse-set-point click) (xref-backend-identifier-at-point (xref-find-backend))) - (define-key-after menu [xref-find-ref] - '(menu-item "Find References" xref-find-references-at-mouse - :help "Find references to identifier") - 'xref-find-def)) - (when (not (xref-marker-stack-empty-p)) - (define-key-after menu [xref-pop] - '(menu-item "Back Definition" xref-pop-marker-stack - :help "Back to the position of the last search") - 'xref-find-ref)) + (define-key-after menu [xref-find-def] + '(menu-item "Find Definition" xref-find-definitions-at-mouse + :help "Find definition of identifier") + 'prog-separator)) menu) (defvar prog-mode-map diff --git a/lisp/replace.el b/lisp/replace.el index 63b58c9b454..947da8a2feb 100644 --- a/lisp/replace.el +++ b/lisp/replace.el @@ -2380,13 +2380,13 @@ See also `multi-occur'." (occur (concat "\\_<" (regexp-quote symbol) "\\_>")))) (defun occur-context-menu (menu click) - "Populate MENU with occur commands for CLICK. + "Populate MENU with occur commands at CLICK. To be added to `context-menu-functions'." (let ((word (thing-at-mouse click 'word)) (sym (thing-at-mouse click 'symbol))) (when (or word sym) (define-key-after menu [occur-separator] menu-bar-separator - 'mark-whole-buffer) + 'middle-separator) (when sym (define-key-after menu [occur-symbol-at-mouse] '(menu-item "Occur Symbol" occur-symbol-at-mouse)