Enhancement to describe-key for a mouse click

[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)))))))

  


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