src/keyboard.h

   1 /* Declarations useful when processing input.
   2    Copyright (C) 1985-1987, 1993, 2001-2012  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Emacs.
   5
   6 GNU Emacs is free software: you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation, either version 3 of the License, or
   9 (at your option) any later version.
  10
  11 GNU Emacs is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #include "systime.h"            /* for EMACS_TIME, Time */
  20 #include "coding.h"             /* for ENCODE_UTF_8 and ENCODE_SYSTEM */
  21
  22 /* Most code should use this macro to access Lisp fields in struct kboard.  */
  23
  24 #define KVAR(kboard, field) ((kboard)->INTERNAL_FIELD (field))
  25
  26 /* Each KBOARD represents one logical input stream from which Emacs
  27    gets input.  If we are using ordinary terminals, it has one KBOARD
  28    object for each terminal device.
  29    Usually each X display screen has its own KBOARD,
  30    but when two of them are on the same X server,
  31    we assume they share a keyboard and give them one KBOARD in common.
  32
  33    Some Lisp variables are per-kboard; they are stored in the KBOARD structure
  34    and accessed indirectly via a Lisp_Misc_Kboard_Objfwd object.
  35
  36    So that definition of keyboard macros, and reading of prefix arguments,
  37    can happen in parallel on various KBOARDs at once,
  38    the state information for those activities is stored in the KBOARD.
  39
  40    Emacs has two states for reading input:
  41
  42    ** Any kboard.  Emacs can accept input from any KBOARD,
  43    and as soon as any of them provides a complete command, Emacs can run it.
  44
  45    ** Single kboard.  Then Emacs is running a command for one KBOARD
  46    and can only read input from that KBOARD.
  47
  48    All input, from all KBOARDs, goes together in a single event queue
  49    at interrupt level.  read_char sees the events sequentially,
  50    but deals with them in accord with the current input state.
  51
  52    In the any-kboard state, read_key_sequence processes input from any KBOARD
  53    immediately.  When a new event comes in from a particular KBOARD,
  54    read_key_sequence switches to that KBOARD.  As a result,
  55    as soon as a complete key arrives from some KBOARD or other,
  56    Emacs starts executing that key's binding.  It switches to the
  57    single-kboard state for the execution of that command,
  58    so that that command can get input only from its own KBOARD.
  59
  60    While in the single-kboard state, read_char can consider input only
  61    from the current KBOARD.  If events come from other KBOARDs, they
  62    are put aside for later in the KBOARDs' kbd_queue lists.
  63    The flag kbd_queue_has_data in a KBOARD is 1 if this has happened.
  64    When Emacs goes back to the any-kboard state, it looks at all the KBOARDs
  65    to find those; and it tries processing their input right away.  */
  66
  67 typedef struct kboard KBOARD;
  68 struct kboard
  69   {
  70     KBOARD *next_kboard;
  71
  72     /* If non-nil, a keymap that overrides all others but applies only to
  73        this KBOARD.  Lisp code that uses this instead of calling read-char
  74        can effectively wait for input in the any-kboard state, and hence
  75        avoid blocking out the other KBOARDs.  See universal-argument in
  76        lisp/simple.el for an example.  */
  77     Lisp_Object INTERNAL_FIELD (Voverriding_terminal_local_map);
  78
  79     /* Last command executed by the editor command loop, not counting
  80        commands that set the prefix argument.  */
  81     Lisp_Object INTERNAL_FIELD (Vlast_command);
  82
  83     /* Normally same as last-command, but never modified by other commands.  */
  84     Lisp_Object INTERNAL_FIELD (Vreal_last_command);
  85
  86     /* User-supplied table to translate input characters through.  */
  87     Lisp_Object INTERNAL_FIELD (Vkeyboard_translate_table);
  88
  89     /* Last command that may be repeated by `repeat'.  */
  90     Lisp_Object INTERNAL_FIELD (Vlast_repeatable_command);
  91
  92     /* The prefix argument for the next command, in raw form.  */
  93     Lisp_Object INTERNAL_FIELD (Vprefix_arg);
  94
  95     /* Saved prefix argument for the last command, in raw form.  */
  96     Lisp_Object INTERNAL_FIELD (Vlast_prefix_arg);
  97
  98     /* Unread events specific to this kboard.  */
  99     Lisp_Object INTERNAL_FIELD (kbd_queue);
 100
 101     /* Non-nil while a kbd macro is being defined.  */
 102     Lisp_Object INTERNAL_FIELD (defining_kbd_macro);
 103
 104     /* The start of storage for the current keyboard macro.  */
 105     Lisp_Object *kbd_macro_buffer;
 106
 107     /* Where to store the next keystroke of the macro.  */
 108     Lisp_Object *kbd_macro_ptr;
 109
 110     /* The finalized section of the macro starts at kbd_macro_buffer and
 111        ends before this.  This is not the same as kbd_macro_ptr, because
 112        we advance this to kbd_macro_ptr when a key's command is complete.
 113        This way, the keystrokes for "end-kbd-macro" are not included in the
 114        macro.  This also allows us to throw away the events added to the
 115        macro by the last command: all the events between kbd_macro_end and
 116        kbd_macro_ptr belong to the last command; see
 117        cancel-kbd-macro-events.  */
 118     Lisp_Object *kbd_macro_end;
 119
 120     /* Allocated size of kbd_macro_buffer.  */
 121     ptrdiff_t kbd_macro_bufsize;
 122
 123     /* Last anonymous kbd macro defined.  */
 124     Lisp_Object INTERNAL_FIELD (Vlast_kbd_macro);
 125
 126     /* Alist of system-specific X windows key symbols.  */
 127     Lisp_Object INTERNAL_FIELD (Vsystem_key_alist);
 128
 129     /* Cache for modify_event_symbol.  */
 130     Lisp_Object INTERNAL_FIELD (system_key_syms);
 131
 132     /* The kind of display: x, w32, ...  */
 133     Lisp_Object INTERNAL_FIELD (Vwindow_system);
 134
 135     /* Keymap mapping keys to alternative preferred forms.
 136        See the DEFVAR for more documentation.  */
 137     Lisp_Object INTERNAL_FIELD (Vlocal_function_key_map);
 138
 139     /* Keymap mapping ASCII function key sequences onto their preferred
 140        forms.  Initialized by the terminal-specific lisp files.  See the
 141        DEFVAR for more documentation.  */
 142     Lisp_Object INTERNAL_FIELD (Vinput_decode_map);
 143
 144     /* Minibufferless frames on this display use this frame's minibuffer.  */
 145     Lisp_Object INTERNAL_FIELD (Vdefault_minibuffer_frame);
 146
 147     /* Number of displays using this KBOARD.  Normally 1, but can be
 148        larger when you have multiple screens on a single X display.  */
 149     int reference_count;
 150
 151     /* The text we're echoing in the modeline - partial key sequences,
 152        usually.  This is nil when not echoing.  */
 153     Lisp_Object INTERNAL_FIELD (echo_string);
 154
 155     /* This flag indicates that events were put into kbd_queue
 156        while Emacs was running for some other KBOARD.
 157        The flag means that, when Emacs goes into the any-kboard state again,
 158        it should check this KBOARD to see if there is a complete command
 159        waiting.
 160
 161        Note that the kbd_queue field can be non-nil even when
 162        kbd_queue_has_data is 0.  When we push back an incomplete
 163        command, then this flag is 0, meaning we don't want to try
 164        reading from this KBOARD again until more input arrives.  */
 165     char kbd_queue_has_data;
 166
 167     /* Nonzero means echo each character as typed.  */
 168     char immediate_echo;
 169
 170     /* If we have echoed a prompt string specified by the user,
 171        this is its length in characters.  Otherwise this is -1.  */
 172     char echo_after_prompt;
 173   };
 174
 175 /* Temporarily used before a frame has been opened. */
 176 extern KBOARD *initial_kboard;
 177
 178 /* In the single-kboard state, this is the kboard
 179    from which input is accepted.
 180
 181    In the any-kboard state, this is the kboard from which we are
 182    right now considering input.  We can consider input from another
 183    kboard, but doing so requires throwing to wrong_kboard_jmpbuf.  */
 184 extern KBOARD *current_kboard;
 185
 186 /* A list of all kboard objects, linked through next_kboard.  */
 187 extern KBOARD *all_kboards;
 188 \f
 189 /* Total number of times read_char has returned, modulo UINTMAX_MAX + 1.  */
 190 extern uintmax_t num_input_events;
 191
 192 /* Nonzero means polling for input is temporarily suppressed.  */
 193 extern int poll_suppress_count;
 194
 195 /* Vector holding the key sequence that invoked the current command.
 196    It is reused for each command, and it may be longer than the current
 197    sequence; this_command_key_count indicates how many elements
 198    actually mean something.  */
 199 extern Lisp_Object this_command_keys;
 200 extern ptrdiff_t this_command_key_count;
 201
 202 /* The frame in which the last input event occurred, or Qmacro if the
 203    last event came from a macro.  We use this to determine when to
 204    generate switch-frame events.  This may be cleared by functions
 205    like Fselect_frame, to make sure that a switch-frame event is
 206    generated by the next character.  */
 207 extern Lisp_Object internal_last_event_frame;
 208 \f
 209 extern Lisp_Object Qrecompute_lucid_menubar, Qactivate_menubar_hook;
 210
 211 /* This holds a Lisp vector that holds the properties of a single
 212    menu item while decoding it in parse_menu_item.
 213    Using a Lisp vector to hold this information while we decode it
 214    takes care of protecting all the data from GC.  */
 215 extern Lisp_Object item_properties;
 216
 217 /* This describes the elements of item_properties.
 218    The first element is not a property, it is a pointer to the item properties
 219    that is saved for GC protection. */
 220 #define ITEM_PROPERTY_ITEM 0
 221 /* The item string.  */
 222 #define ITEM_PROPERTY_NAME 1
 223 /* Start of initialize to nil */
 224 /* The binding: nil, a command or a keymap.  */
 225 #define ITEM_PROPERTY_DEF 2
 226 /* The keymap if the binding is a keymap, otherwise nil.  */
 227 #define ITEM_PROPERTY_MAP 3
 228 /* Nil, :radio or :toggle.  */
 229 #define ITEM_PROPERTY_TYPE 4
 230 /* Nil or a string describing an equivalent key binding.  */
 231 #define ITEM_PROPERTY_KEYEQ 5
 232 /* Not nil if a selected toggle box or radio button, otherwise nil.  */
 233 #define ITEM_PROPERTY_SELECTED 6
 234 /* Place for a help string. Not yet used.  */
 235 #define ITEM_PROPERTY_HELP 7
 236 /* Start of initialize to t */
 237 /* Last property. */
 238 /* Not nil if item is enabled.  */
 239 #define ITEM_PROPERTY_ENABLE 8
 240
 241 /* This holds a Lisp vector that holds the results of decoding
 242    the keymaps or alist-of-alists that specify a menu.
 243
 244    It describes the panes and items within the panes.
 245
 246    Each pane is described by 3 elements in the vector:
 247    t, the pane name, the pane's prefix key.
 248    Then follow the pane's items, with 5 elements per item:
 249    the item string, the enable flag, the item's value,
 250    the definition, and the equivalent keyboard key's description string.
 251
 252    In some cases, multiple levels of menus may be described.
 253    A single vector slot containing nil indicates the start of a submenu.
 254    A single vector slot containing lambda indicates the end of a submenu.
 255    The submenu follows a menu item which is the way to reach the submenu.
 256
 257    A single vector slot containing quote indicates that the
 258    following items should appear on the right of a dialog box.
 259
 260    Using a Lisp vector to hold this information while we decode it
 261    takes care of protecting all the data from GC.  */
 262 extern Lisp_Object menu_items;
 263
 264 /* If non-nil, means that the global vars defined here are already in use.
 265    Used to detect cases where we try to re-enter this non-reentrant code.  */
 266 #if defined USE_GTK || defined USE_MOTIF
 267 extern Lisp_Object menu_items_inuse;
 268 #endif
 269
 270 /* Number of slots currently allocated in menu_items.  */
 271 extern int menu_items_allocated;
 272
 273 /* This is the index in menu_items of the first empty slot.  */
 274 extern int menu_items_used;
 275
 276 /* The number of panes currently recorded in menu_items,
 277    excluding those within submenus.  */
 278 extern int menu_items_n_panes;
 279
 280 #define MENU_ITEMS_PANE_NAME 1
 281 #define MENU_ITEMS_PANE_PREFIX 2
 282 #define MENU_ITEMS_PANE_LENGTH 3
 283
 284 enum menu_item_idx
 285 {
 286   MENU_ITEMS_ITEM_NAME = 0,
 287   MENU_ITEMS_ITEM_ENABLE,
 288   MENU_ITEMS_ITEM_VALUE,
 289   MENU_ITEMS_ITEM_EQUIV_KEY,
 290   MENU_ITEMS_ITEM_DEFINITION,
 291   MENU_ITEMS_ITEM_TYPE,
 292   MENU_ITEMS_ITEM_SELECTED,
 293   MENU_ITEMS_ITEM_HELP,
 294   MENU_ITEMS_ITEM_LENGTH
 295 };
 296
 297 extern Lisp_Object unuse_menu_items (Lisp_Object dummy);
 298
 299 /* This is how to deal with multibyte text if HAVE_MULTILINGUAL_MENU
 300    isn't defined.  The use of HAVE_MULTILINGUAL_MENU could probably be
 301    confined to an extended version of this with sections of code below
 302    using it unconditionally.  */
 303 #ifndef HAVE_NTGUI
 304 #if defined (USE_GTK) || defined (HAVE_NS)
 305 # define ENCODE_MENU_STRING(str) ENCODE_UTF_8 (str)
 306 #elif defined HAVE_X_I18N
 307 #define ENCODE_MENU_STRING(str) ENCODE_SYSTEM (str)
 308 #else
 309 #define ENCODE_MENU_STRING(str) string_make_unibyte (str)
 310 #endif /* USE_GTK  */
 311 #else /* HAVE_NTGUI */
 312 #define ENCODE_MENU_STRING(str) (str)
 313 #endif
 314
 315 #if defined (HAVE_NS) || defined (HAVE_NTGUI) || defined (USE_GTK)
 316
 317 /* Definitions copied from lwlib.h */
 318
 319 enum button_type
 320 {
 321   BUTTON_TYPE_NONE,
 322   BUTTON_TYPE_TOGGLE,
 323   BUTTON_TYPE_RADIO
 324 };
 325
 326 /* This structure is based on the one in ../lwlib/lwlib.h, with unused portions
 327    removed.  No term uses these. */
 328 typedef struct _widget_value
 329 {
 330   /* name of widget */
 331   Lisp_Object   lname;
 332   const char*   name;
 333   /* value (meaning depend on widget type) */
 334   const char*   value;
 335   /* keyboard equivalent. no implications for XtTranslations */
 336   Lisp_Object   lkey;
 337   const char*   key;
 338   /* Help string or nil if none.
 339      GC finds this string through the frame's menu_bar_vector
 340      or through menu_items.  */
 341   Lisp_Object   help;
 342   /* true if enabled */
 343   unsigned char enabled;
 344   /* true if selected */
 345   unsigned char selected;
 346   /* The type of a button.  */
 347   enum button_type button_type;
 348 #if defined (HAVE_NTGUI)
 349   /* true if menu title */
 350   unsigned char title;
 351 #endif
 352   /* Contents of the sub-widgets, also selected slot for checkbox */
 353   struct _widget_value* contents;
 354   /* data passed to callback */
 355   void  *call_data;
 356   /* next one in the list */
 357   struct _widget_value* next;
 358 #ifdef USE_GTK
 359   struct _widget_value *free_list;
 360 #endif
 361 } widget_value;
 362
 363 #endif /* HAVE_NS || HAVE_NTGUI */
 364
 365 \f
 366 /* Macros for dealing with lispy events.  */
 367
 368 /* True if EVENT has data fields describing it (i.e. a mouse click).  */
 369 #define EVENT_HAS_PARAMETERS(event) (CONSP (event))
 370
 371 /* Extract the head from an event.
 372    This works on composite and simple events.  */
 373 #define EVENT_HEAD(event) \
 374   (EVENT_HAS_PARAMETERS (event) ? XCAR (event) : (event))
 375
 376 /* Extract the starting and ending positions from a composite event.  */
 377 #define EVENT_START(event) (XCAR (XCDR (event)))
 378 #define EVENT_END(event) (XCAR (XCDR (XCDR (event))))
 379
 380 /* Extract the click count from a multi-click event.  */
 381 #define EVENT_CLICK_COUNT(event) (Fnth (make_number (2), (event)))
 382
 383 /* Extract the fields of a position.  */
 384 #define POSN_WINDOW(posn) (XCAR (posn))
 385 #define POSN_POSN(posn) (XCAR (XCDR (posn)))
 386 #define POSN_SET_POSN(posn,x) (XSETCAR (XCDR (posn), (x)))
 387 #define POSN_WINDOW_POSN(posn) (XCAR (XCDR (XCDR (posn))))
 388 #define POSN_TIMESTAMP(posn) (XCAR (XCDR (XCDR (XCDR (posn)))))
 389 #define POSN_SCROLLBAR_PART(posn)       (Fnth (make_number (4), (posn)))
 390
 391 /* A cons (STRING . STRING-CHARPOS), or nil in mouse-click events.
 392    It's a cons if the click is over a string in the mode line.  */
 393
 394 #define POSN_STRING(posn) (Fnth (make_number (4), (posn)))
 395
 396 /* If POSN_STRING is nil, event refers to buffer location.  */
 397
 398 #define POSN_INBUFFER_P(posn) (NILP (POSN_STRING (posn)))
 399 #define POSN_BUFFER_POSN(posn) (Fnth (make_number (5), (posn)))
 400
 401 /* Some of the event heads.  */
 402 extern Lisp_Object Qswitch_frame;
 403
 404 /* Properties on event heads.  */
 405 extern Lisp_Object Qevent_kind;
 406
 407 /* The values of Qevent_kind properties.  */
 408 extern Lisp_Object Qmouse_click;
 409
 410 extern Lisp_Object Qhelp_echo;
 411
 412 /* Getting the kind of an event head.  */
 413 #define EVENT_HEAD_KIND(event_head) \
 414   (Fget ((event_head), Qevent_kind))
 415
 416 /* Symbols to use for non-text mouse positions.  */
 417 extern Lisp_Object Qmode_line, Qvertical_line, Qheader_line;
 418
 419 /* True while doing kbd input.  */
 420 extern int waiting_for_input;
 421
 422 /* Address (if not 0) of EMACS_TIME to zero out if a SIGIO interrupt
 423    happens.  */
 424 extern EMACS_TIME *input_available_clear_time;
 425
 426 #if defined HAVE_WINDOW_SYSTEM && !defined USE_GTK && !defined HAVE_NS
 427 extern int ignore_mouse_drag_p;
 428 #endif
 429
 430 /* The primary selection.  */
 431 extern Lisp_Object QPRIMARY;
 432
 433 /* Forward declaration for prototypes.  */
 434 struct input_event;
 435
 436 extern Lisp_Object parse_modifiers (Lisp_Object);
 437 extern Lisp_Object reorder_modifiers (Lisp_Object);
 438 extern Lisp_Object read_char (int, ptrdiff_t, Lisp_Object *, Lisp_Object,
 439                               int *, EMACS_TIME *);
 440 extern int parse_solitary_modifier (Lisp_Object symbol);
 441
 442
 443 /* This is like Vthis_command, except that commands never set it.  */
 444 extern Lisp_Object real_this_command;
 445
 446 /* Non-nil disable property on a command means
 447    do not execute it; call disabled-command-function's value instead.  */
 448 extern Lisp_Object QCtoggle, QCradio;
 449
 450 /* An event header symbol HEAD may have a property named
 451    Qevent_symbol_element_mask, which is of the form (BASE MODIFIERS);
 452    BASE is the base, unmodified version of HEAD, and MODIFIERS is the
 453    mask of modifiers applied to it.  If present, this is used to help
 454    speed up parse_modifiers.  */
 455 extern Lisp_Object Qevent_symbol_element_mask;
 456
 457 /* The timestamp of the last input event we received from the X server.
 458    X Windows wants this for selection ownership.  */
 459 extern Time last_event_timestamp;
 460
 461 extern int quit_char;
 462
 463 extern int timers_run;
 464
 465 extern int menu_separator_name_p (const char *);
 466 extern int parse_menu_item (Lisp_Object, int);
 467
 468 extern void init_kboard (KBOARD *);
 469 extern void delete_kboard (KBOARD *);
 470 extern void not_single_kboard_state (KBOARD *);
 471 extern void push_kboard (struct kboard *);
 472 extern void push_frame_kboard (struct frame *);
 473 extern void pop_kboard (void);
 474 extern void temporarily_switch_to_single_kboard (struct frame *);
 475 extern void record_asynch_buffer_change (void);
 476 extern void input_poll_signal (int);
 477 extern void start_polling (void);
 478 extern void stop_polling (void);
 479 extern void set_poll_suppress_count (int);
 480 extern void gobble_input (int);
 481 extern int input_polling_used (void);
 482 extern void clear_input_pending (void);
 483 extern int requeued_events_pending_p (void);
 484 extern void bind_polling_period (int);
 485 extern int make_ctrl_char (int) ATTRIBUTE_CONST;
 486 extern void stuff_buffered_input (Lisp_Object);
 487 extern void clear_waiting_for_input (void);
 488 extern void swallow_events (int);
 489 extern int lucid_event_type_list_p (Lisp_Object);
 490 extern void kbd_buffer_store_event (struct input_event *);
 491 extern void kbd_buffer_store_event_hold (struct input_event *,
 492                                          struct input_event *);
 493 extern void kbd_buffer_unget_event (struct input_event *);
 494 extern void poll_for_input_1 (void);
 495 extern void show_help_echo (Lisp_Object, Lisp_Object, Lisp_Object,
 496                             Lisp_Object);
 497 extern void gen_help_event (Lisp_Object, Lisp_Object, Lisp_Object,
 498                             Lisp_Object, ptrdiff_t);
 499 extern void kbd_buffer_store_help_event (Lisp_Object, Lisp_Object);
 500 extern Lisp_Object menu_item_eval_property (Lisp_Object);
 501 extern int  kbd_buffer_events_waiting (int);
 502 extern void add_user_signal (int, const char *);
 503
 504 extern int tty_read_avail_input (struct terminal *, int,
 505                                  struct input_event *);
 506 extern EMACS_TIME timer_check (void);
 507 extern void mark_kboards (void);
 508
 509 #ifdef WINDOWSNT
 510 extern const char *const lispy_function_keys[];
 511 #endif