Enhancement to describe-key for a mouse click

[storm@cua.dk (Kim F. Storm)]

Try this:

C-h k <click mouse-1>

The output describes the down event <down-mouse-1> but there is no way
to get a description of the the corresponding up event <mouse-1>.

The following patch adds a description of the up event, so both the
down and up events are described.

Since (interactive "k") reads and discards the up-event (for good
reasons), I needed to introduce a new interactive code letter "U" that
can be used after "k" (and "K") to return the last discarded up event.


*** src/callint.c	02 Aug 2004 00:43:28 +0200	1.133
--- src/callint.c	24 Oct 2004 22:06:31 +0200
***************
*** 110,115 ****
--- 110,116 ----
  r -- Region: point and mark as 2 numeric args, smallest first.  Does no I/O.
  s -- Any string.  Does not inherit the current input method.
  S -- Any symbol.
+ U -- Mouse up event discarded by a previous k or K argument.
  v -- Variable name: symbol that is user-variable-p.
  x -- Lisp expression read but not evaluated.
  X -- Lisp expression read and evaluated.
***************
*** 268,273 ****
--- 269,275 ----
    Lisp_Object specs;
    Lisp_Object filter_specs;
    Lisp_Object teml;
+   Lisp_Object up_event;
    Lisp_Object enable;
    int speccount = SPECPDL_INDEX ();

***************
*** 289,295 ****
    char prompt1[100];
    char *tem1;
    int arg_from_tty = 0;
!   struct gcpro gcpro1, gcpro2, gcpro3, gcpro4;
    int key_count;
    int record_then_fail = 0;

--- 291,297 ----
    char prompt1[100];
    char *tem1;
    int arg_from_tty = 0;
!   struct gcpro gcpro1, gcpro2, gcpro3, gcpro4, gcpro5;
    int key_count;
    int record_then_fail = 0;

***************
*** 328,333 ****
--- 330,338 ----
       The feature is not fully implemented.  */
    filter_specs = Qnil;

+   /* If k or K discard an up-event, save it here so it can be retrieved with U */
+   up_event = Qnil;
+
    /* Decode the kind of function.  Either handle it and return,
       or go to `lose' if not interactive, or go to `retry'
       to specify a different function, or set either STRING or SPECS.  */
***************
*** 499,505 ****
        varies[i] = 0;
      }

!   GCPRO4 (prefix_arg, function, *args, *visargs);
    gcpro3.nvars = (count + 1);
    gcpro4.nvars = (count + 1);

--- 504,510 ----
        varies[i] = 0;
      }

!   GCPRO5 (prefix_arg, function, *args, *visargs, up_event);
    gcpro3.nvars = (count + 1);
    gcpro4.nvars = (count + 1);

***************
*** 628,634 ****
  		/* Ignore first element, which is the base key.  */
  		tem2 = Fmemq (intern ("down"), Fcdr (teml));
  		if (! NILP (tem2))
! 		  Fread_event (Qnil, Qnil);
  	      }
  	  }
  	  break;
--- 633,639 ----
  		/* Ignore first element, which is the base key.  */
  		tem2 = Fmemq (intern ("down"), Fcdr (teml));
  		if (! NILP (tem2))
! 		  up_event = Fread_event (Qnil, Qnil);
  	      }
  	  }
  	  break;
***************
*** 656,666 ****
  		/* Ignore first element, which is the base key.  */
  		tem2 = Fmemq (intern ("down"), Fcdr (teml));
  		if (! NILP (tem2))
! 		  Fread_event (Qnil, Qnil);
  	      }
  	  }
  	  break;

  	case 'e':		/* The invoking event.  */
  	  if (next_event >= key_count)
  	    error ("%s must be bound to an event with parameters",
--- 661,681 ----
  		/* Ignore first element, which is the base key.  */
  		tem2 = Fmemq (intern ("down"), Fcdr (teml));
  		if (! NILP (tem2))
! 		  up_event = Fread_event (Qnil, Qnil);
  	      }
  	  }
  	  break;

+ 	case 'U':		/* Up event from last k or K */
+ 	  if (!NILP (up_event))
+ 	    {
+ 	      args[i] = Fmake_vector (make_number (1), up_event);
+ 	      up_event = Qnil;
+ 	      teml = args[i];
+ 	      visargs[i] = Fkey_description (teml, Qnil);
+ 	    }
+ 	  break;
+
  	case 'e':		/* The invoking event.  */
  	  if (next_event >= key_count)
  	    error ("%s must be bound to an event with parameters",


*** lisp/help.el	13 Oct 2004 23:25:59 +0200	1.267
--- lisp/help.el	24 Oct 2004 22:11:01 +0200
***************
*** 573,586 ****
  			 (if (symbolp defn) defn (prin1-to-string defn)))))))))


! (defun describe-key (key &optional untranslated)
    "Display documentation of the function invoked by KEY.
  KEY should be a key sequence--when calling from a program,
  pass a string or a vector.
  If non-nil UNTRANSLATED is a vector of the untranslated events.
  It can also be a number in which case the untranslated events from
  the last key hit are used."
!   (interactive "kDescribe key: \np")
    (if (numberp untranslated)
        (setq untranslated (this-single-command-raw-keys)))
    (save-excursion
--- 573,586 ----
  			 (if (symbolp defn) defn (prin1-to-string defn)))))))))


! (defun describe-key (key &optional untranslated up-event)
    "Display documentation of the function invoked by KEY.
  KEY should be a key sequence--when calling from a program,
  pass a string or a vector.
  If non-nil UNTRANSLATED is a vector of the untranslated events.
  It can also be a number in which case the untranslated events from
  the last key hit are used."
!   (interactive "kDescribe key: \np\nU")
    (if (numberp untranslated)
        (setq untranslated (this-single-command-raw-keys)))
    (save-excursion
***************
*** 608,613 ****
--- 608,624 ----
  	    (prin1 defn)
  	    (princ "\n   which is ")
  	    (describe-function-1 defn)
+ 	    (when up-event
+ 	      (let ((defn (or (string-key-binding up-event) (key-binding up-event))))
+ 		(unless (or (null defn) (integerp defn) (equal defn 'undefined))
+ 		  (princ "\n\n-------------- up event ---------------\n\n")
+ 		  (princ (key-description up-event))
+ 		  (if (windowp window)
+ 		      (princ " at that spot"))
+ 		  (princ " runs the command ")
+ 		  (prin1 defn)
+ 		  (princ "\n   which is ")
+ 		  (describe-function-1 defn))))
  	    (print-help-return-message)))))))

  \f


--
Kim F. Storm <storm@cua.dk> http://www.cua.dk