Working with Input Events

• Functions which work with key sequences now handle non-character events. Functions like define-key, global-set-key, and local-set-key used to accept strings representing key sequences; now, since events may be arbitrary lisp objects, they also accept vectors. The function read-key-sequence may return a string or a vector, depending on whether or not the sequence read contains only characters. List events may be represented by the symbols at their head; to bind clicks of the left mouse button, you need only present the symbol mouse-1, not an entire mouse click event. If you do put an event which is a list in a key sequence, only the event's head symbol is used in key lookups. For example, to globally bind the left mouse button to the function mouse-set-point, you could evaluate this:

  (global-set-key [mouse-1] 'mouse-set-point)
  

  To bind the sequence C-c F1 to the command tex-view in tex-mode-map, you could evaluate this:

  (define-key tex-mode-map [?\C-c f1] 'tex-view)
  

  To find the binding for the function key labeled NEXT in minibuffer-local-map, you could evaluate this:

  (lookup-key minibuffer-local-map [next])
       => next-history-element
  

  If you call the function read-key-sequence and then press C-x C-F5, here is how it behaves:

  (read-key-sequence "Press `C-x C-F5': ")
       => [24 C-f5]
  

  Note that `24' is the character C-x.
• The documentation functions (single-key-description, key-description, etc.) now handle the new event types. Wherever a string of keyboard input characters was acceptable in previous versions of Emacs, a vector of events should now work.
• Special parts of a window can have their own bindings for mouse events. When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event itself shows nothing special--only the symbol that would normally represent that mouse button and modifier keys. The information about the screen region is kept in other parts of the event list. But read-key-sequence translates this information into imaginary prefix keys, all of which are symbols: mode-line, vertical-line, and vertical-scroll-bar. For example, if you call read-key-sequence and then click the mouse on the window's mode line, this is what happens:

  (read-key-sequence "Click on the mode line: ")
       => [mode-line (mouse-1 (#<window 6 on NEWS> mode-line
                                (40 . 63) 5959987))]
  

  You can define meanings for mouse clicks in special window regions by defining key sequences using these imaginary prefix keys. For example, here is how to bind the third mouse button on a window's mode line delete the window:

  (global-set-key [mode-line mouse-3] 'mouse-delete-window)
  

  Here's how to bind the middle button (modified by META) on the vertical line at the right of a window to scroll the window to the left.

  (global-set-key [vertical-line M-mouse-2] 'scroll-left)
  

• Decomposing an event symbol. Each symbol used to identify a function key or mouse button has a property named event-symbol-elements, which is a list containing an unmodified version of the symbol, followed by modifiers the symbol name contains. The modifiers are symbols; they include shift, control, and meta. In addition, a mouse event symbol has one of click, drag, and down. For example:

  (get 'f5 'event-symbol-elements)
       => (f5)
  (get 'C-f5 'event-symbol-elements)
       => (f5 control)
  (get 'M-S-f5 'event-symbol-elements)
       => (f5 meta shift)
  (get 'mouse-1 'event-symbol-elements)
       => (mouse-1 click)
  (get 'down-mouse-1 'event-symbol-elements)
       => (mouse-1 down)
  

  Note that the event-symbol-elements property for a mouse click explicitly contains click, but the event symbol name itself does not contain `click'.
• Use read-event to read input if you want to accept any kind of event. The old function read-char now discards events other than keyboard characters.
• last-command-char and last-input-char can now hold any kind of event.
• The new variable unread-command-events is much like unread-command-char. Its value is a list of events of any type, to be processed as command input in order of appearance in the list.
• The function this-command-keys may return a string or a vector, depending on whether or not the sequence read contains only characters. You may need to upgrade code which uses this function. The function recent-keys now returns a vector of events. You may need to upgrade code which uses this function.
• A keyboard macro's definition can now be either a string or a vector. All that really matters is what elements it has. If the elements are all characters, then the macro can be a string; otherwise, it has to be a vector.
• The variable last-event-frame records which frame the last input event was directed to. Usually this is the frame that was selected when the event was generated, but if that frame has redirected input focus to another frame, last-event-frame is the frame to which the event was redirected.
• The interactive specification now allows a new code letter `e' to simplify commands bound to events which are lists. This code supplies as an argument the complete event object. You can use `e' more than once in a single command's interactive specification. If the key sequence which invoked the command has n events with parameters, the nth `e' provides the nth parameterized event. Events which are not lists, such as function keys and ASCII keystrokes, do not count where `e' is concerned.
• You can extract the starting and ending position values from a mouse button or motion event using the two functions event-start and event-end. These two functions return different values for drag and motion events; for click and button-down events, they both return the position of the event.
• The position, a returned by event-start and event-end, is a list of this form:

  (window buffer-position (col . row) timestamp)
  

  You can extract parts of this list with the functions posn-window, posn-point, posn-col-row, and posn-timestamp.
• The function scroll-bar-scale is useful for computing where to scroll to in response to a mouse button event from a scroll bar. It takes two arguments, ratio and total, and in effect multiplies them. We say "in effect" because ratio is not a number; rather a pair (num . denom). Here's the usual way to use scroll-bar-scale:

  (scroll-bar-scale (posn-col-row (event-start event))
                    (buffer-size))