New Input Event Formats

Mouse clicks, mouse movements and function keys no longer appear in the input stream as characters; instead, other kinds of Lisp objects represent them as input.

• An ordinary input character event consists of a basic code between 0 and 255, plus any or all of these modifier bits:

  meta

  The 2**23 bit in the character code indicates a character typed with the meta key held down.

  control

  The 2**22 bit in the character code indicates a non-ASCII control character. ASCII control characters such as C-a have special basic codes of their own, so Emacs needs no special bit to indicate them. Thus, the code for C-a is just 1. But if you type a control combination not in ASCII, such as % with the control key, the numeric value you get is the code for % plus 2**22 (assuming the terminal supports non-ASCII control characters).

  shift

  The 2**21 bit in the character code indicates an ASCII control character typed with the shift key held down. For letters, the basic code indicates upper versus lower case; for digits and punctuation, the shift key selects an entirely different character with a different basic code. In order to keep within the ASCII character set whenever possible, Emacs avoids using the 2**21 bit for those characters. However, ASCII provides no way to distinguish C-A from C-a, so Emacs uses the 2**21 bit in C-A and not in C-a.

  hyper

  The 2**20 bit in the character code indicates a character typed with the hyper key held down.

  super

  The 2**19 bit in the character code indicates a character typed with the super key held down.

  alt

  The 2**18 bit in the character code indicates a character typed with the alt key held down. (On some terminals, the key labeled ALT is actually the meta key.)

  In the future, Emacs may support a larger range of basic codes. We may also move the modifier bits to larger bit numbers. Therefore, you should avoid mentioning specific bit numbers in your program. Instead, the way to test the modifier bits of a character is with the function event-modifiers (see below).
• Function keys are represented as symbols. The symbol's name is the function key's label. For example, pressing a key labeled F1 places the symbol f1 in the input stream. There are a few exceptions to the symbol naming convention:

  kp-add, kp-decimal, kp-divide, ...

  Keypad keys (to the right of the regular keyboard).

  kp-0, kp-1, ...

  Keypad keys with digits.

  kp-f1, kp-f2, kp-f3, kp-f4

  Keypad PF keys.

  left, up, right, down

  Cursor arrow keys

  You can use the modifier keys CTRL, META, HYPER, SUPER, ALT and SHIFT with function keys. The way to represent them is with prefixes in the symbol name:

  `A-'

  The alt modifier.

  `C-'

  The control modifier.

  `H-'

  The hyper modifier.

  `M-'

  The meta modifier.

  `s-'

  The super modifier.

  `S-'

  The shift modifier.

  Thus, the symbol for the key F3 with META held down is M-F3. When you use more than one prefix, we recommend you write them in alphabetical order (though the order does not matter in arguments to the key-binding lookup and modification functions).
• Mouse events are represented as lists. If you press a mouse button and release it at the same location, this generates a "click" event. Mouse click events have this form:

  (button-symbol
   (window (column . row)
    buffer-pos timestamp))
  

  Here is what the elements normally mean:

  button-symbol

  indicates which mouse button was used. It is one of the symbols mouse-1, mouse-2, ..., where the buttons are normally numbered left to right. You can also use prefixes `A-', `C-', `H-', `M-', `S-' and `s-' for modifiers alt, control, hyper, meta, shift and super, just as you would with function keys.

  window

  is the window in which the click occurred.

  column

  row

  are the column and row of the click, relative to the top left corner of window, which is (0 . 0).

  buffer-pos

  is the buffer position of the character clicked on.

  timestamp

  is the time at which the event occurred, in milliseconds. (Since this value wraps around the entire range of Emacs Lisp integers in about five hours, it is useful only for relating the times of nearby events.)

  The meanings of buffer-pos, row and column are somewhat different when the event location is in a special part of the screen, such as the mode line or a scroll bar. If the position is in the window's scroll bar, then buffer-pos is the symbol vertical-scroll-bar, and the pair (column . row) is replaced with a pair (portion . whole), where portion is the distance of the click from the top or left end of the scroll bar, and whole is the length of the entire scroll bar. If the position is on a mode line or the vertical line separating window from its neighbor to the right, then buffer-pos is the symbol mode-line or vertical-line. In this case row and column do not have meaningful data.
• Releasing a mouse button above a different character position generates a "drag" event, which looks like this:

  (button-symbol
   (window1 (column1 . row1)
    buffer-pos1 timestamp1)
   (window2 (column2 . row2)
    buffer-pos2 timestamp2))
  

  The name of button-symbol contains the prefix `drag-'. The second and third elements of the event give the starting and ending position of the drag. The `drag-' prefix follows the modifier key prefixes such as `C-' and `M-'. If read-key-sequence receives a drag event which has no key binding, and the corresponding click event does have a binding, it changes the drag event into a click event at the drag's starting position. This means that you don't have to distinguish between click and drag events unless you want to.
• Click and drag events happen when you release a mouse button. Another kind of event happens when you press a button. It looks just like a click event, except that the name of button-symbol contains the prefix `down-'. The `down-' prefix follows the modifier key prefixes such as `C-' and `M-'. The function read-key-sequence, and the Emacs command loop, ignore any down events that don't have command bindings. This means that you need not worry about defining down events unless you want them to do something. The usual reason to define a down event is so that you can track mouse motion until the button is released.
• For example, if the user presses and releases the left mouse button over the same location, Emacs generates a sequence of events like this:

  (down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
  (mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))
  

  Or, while holding the control key down, the user might hold down the second mouse button, and drag the mouse from one line to the next. That produces two events, as shown here:

  (C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
  (C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                  (#<window 18 on NEWS> 3510 (0 . 28) -729648))
  

  Or, while holding down the meta and shift keys, the user might press the second mouse button on the window's mode line, and then drag the mouse into another window. That produces an event like this:

  (M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
  (M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                    (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                     -453816))
  

• A key sequence that starts with a mouse click is read using the keymaps of the buffer in the window clicked on, not the current buffer. This does not imply that clicking in a window selects that window or its buffer. The execution of the command begins with no change in the selected window or current buffer. However, the command can switch windows or buffers if programmed to do so.
• Mouse motion events are represented by lists. During the execution of the body of a track-mouse form, moving the mouse generates events that look like this:

  (mouse-movement (window (column . row)
                   buffer-pos timestamp))
  

  The second element of the list describes the current position of the mouse, just as in a mouse click event. Outside of track-mouse forms, Emacs does not generate events for mere motion of the mouse, and these events do not appear.
• Focus shifts between frames are represented by lists. When the mouse shifts temporary input focus from one frame to another, Emacs generates an event like this:

  (switch-frame new-frame)
  

  where new-frame is the frame switched to. In X windows, most window managers are set up so that just moving the mouse into a window is enough to set the focus there. As far as the user is concerned, Emacs behaves consistently with this. However, there is no need for the Lisp program to know about the focus change until some other kind of input arrives. So Emacs generates the focus event only when the user actually types a keyboard key or presses a mouse button in the new frame; just moving the mouse between frames does not generate a focus event. The global key map usually binds this event to the internal-select-frame function, so that characters typed at a frame apply to that frame's selected window. If the user switches frames in the middle of a key sequence, then Emacs delays the switch-frame event until the key sequence is over. For example, suppose C-c C-a is a key sequence in the current buffer's keymaps. If the user types C-c, moves the mouse to another frame, and then types C-a, read-key-sequence returns the sequence "\C-c\C-a", and the next call to read-event or read-key-sequence will return the switch-frame event.