1: /* Declarations useful when processing input.
    2:    Copyright (C) 1985, 1986, 1987, 1993, 2001, 2002, 2003, 2004,
    3:                  2005, 2006, 2007  Free Software Foundation, Inc.
    4: 
    5: This file is part of GNU Emacs.
    6: 
    7: GNU Emacs is free software; you can redistribute it and/or modify
    8: it under the terms of the GNU General Public License as published by
    9: the Free Software Foundation; either version 2, or (at your option)
   10: any later version.
   11: 
   12: GNU Emacs is distributed in the hope that it will be useful,
   13: but WITHOUT ANY WARRANTY; without even the implied warranty of
   14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   15: GNU General Public License for more details.
   16: 
   17: You should have received a copy of the GNU General Public License
   18: along with GNU Emacs; see the file COPYING.  If not, write to
   19: the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   20: Boston, MA 02110-1301, USA.  */
   21: 
   22: #include "systime.h"            /* for EMACS_TIME */
   23: 
   24: /* Length of echobuf field in each KBOARD.  */
   25: 
   26: /* Each KBOARD represents one logical input stream from which Emacs gets input.
   27:    If we are using an ordinary terminal, it has one KBOARD object.
   28:    Usually each X display screen has its own KBOARD,
   29:    but when two of them are on the same X server,
   30:    we assume they share a keyboard and give them one KBOARD in common.
   31: 
   32:    Some Lisp variables are per-kboard; they are stored in the KBOARD structure
   33:    and accessed indirectly via a Lisp_Misc_Kboard_Objfwd object.
   34: 
   35:    So that definition of keyboard macros, and reading of prefix arguments,
   36:    can happen in parallel on various KBOARDs at once,
   37:    the state information for those activities is stored in the KBOARD.
   38: 
   39:    Emacs has two states for reading input:
   40: 
   41:    ** Any kboard.  Emacs can accept input from any KBOARD,
   42:    and as soon as any of them provides a complete command, Emacs can run it.
   43: 
   44:    ** Single kboard.  Then Emacs is running a command for one KBOARD
   45:    and can only read input from that KBOARD.
   46: 
   47:    All input, from all KBOARDs, goes together in a single event queue
   48:    at interrupt level.  read_char sees the events sequentially,
   49:    but deals with them in accord with the current input state.
   50: 
   51:    In the any-kboard state, read_key_sequence processes input from any KBOARD
   52:    immediately.  When a new event comes in from a particular KBOARD,
   53:    read_key_sequence switches to that KBOARD.  As a result,
   54:    as soon as a complete key arrives from some KBOARD or other,
   55:    Emacs starts executing that key's binding.  It switches to the
   56:    single-kboard state for the execution of that command,
   57:    so that that command can get input only from its own KBOARD.
   58: 
   59:    While in the single-kboard state, read_char can consider input only
   60:    from the current KBOARD.  If events come from other KBOARDs, they
   61:    are put aside for later in the KBOARDs' kbd_queue lists.
   62:    The flag kbd_queue_has_data in a KBOARD is 1 if this has happened.
   63:    When Emacs goes back to the any-kboard state, it looks at all the KBOARDs
   64:    to find those; and it tries processing their input right away.  */
   65: 
   66: typedef struct kboard KBOARD;
   67: struct kboard
   68:   {
   69:     KBOARD *next_kboard;
   70: 
   71:     /* If non-nil, a keymap that overrides all others but applies only to
   72:        this KBOARD.  Lisp code that uses this instead of calling read-char
   73:        can effectively wait for input in the any-kboard state, and hence
   74:        avoid blocking out the other KBOARDs.  See universal-argument in
   75:        lisp/simple.el for an example.  */
   76:     Lisp_Object Voverriding_terminal_local_map;
   77: 
   78:     /* Last command executed by the editor command loop, not counting
   79:        commands that set the prefix argument.  */
   80:     Lisp_Object Vlast_command;
   81: 
   82:     /* Normally same as last-command, but never modified by
   83:        other commands.  */
   84:     Lisp_Object Vreal_last_command;
   85: 
   86:     /* The prefix argument for the next command, in raw form.  */
   87:     Lisp_Object Vprefix_arg;
   88: 
   89:     /* Saved prefix argument for the last command, in raw form.  */
   90:     Lisp_Object Vlast_prefix_arg;
   91: 
   92:     /* Unread events specific to this kboard.  */
   93:     Lisp_Object kbd_queue;
   94: 
   95:     /* Non-nil while a kbd macro is being defined.  */
   96:     Lisp_Object defining_kbd_macro;
   97: 
   98:     /* The start of storage for the current keyboard macro.  */
   99:     Lisp_Object *kbd_macro_buffer;
  100: 
  101:     /* Where to store the next keystroke of the macro.  */
  102:     Lisp_Object *kbd_macro_ptr;
  103: 
  104:     /* The finalized section of the macro starts at kbd_macro_buffer and
  105:        ends before this.  This is not the same as kbd_macro_ptr, because
  106:        we advance this to kbd_macro_ptr when a key's command is complete.
  107:        This way, the keystrokes for "end-kbd-macro" are not included in the
  108:        macro.  This also allows us to throw away the events added to the
  109:        macro by the last command: all the events between kbd_macro_end and
  110:        kbd_macro_ptr belong to the last command; see
  111:        cancel-kbd-macro-events.  */
  112:     Lisp_Object *kbd_macro_end;
  113: 
  114:     /* Allocated size of kbd_macro_buffer.  */
  115:     int kbd_macro_bufsize;
  116: 
  117:     /* Last anonymous kbd macro defined.  */
  118:     Lisp_Object Vlast_kbd_macro;
  119: 
  120:     /* Alist of system-specific X windows key symbols.  */
  121:     Lisp_Object Vsystem_key_alist;
  122: 
  123:     /* Cache for modify_event_symbol.  */
  124:     Lisp_Object system_key_syms;
  125: 
  126:     /* Minibufferless frames on this display use this frame's minibuffer.  */
  127:     Lisp_Object Vdefault_minibuffer_frame;
  128: 
  129:     /* Number of displays using this KBOARD.  Normally 1, but can be
  130:        larger when you have multiple screens on a single X display.  */
  131:     int reference_count;
  132: 
  133:     /* The text we're echoing in the modeline - partial key sequences,
  134:        usually.  This is nil when not echoing.  */
  135:     Lisp_Object echo_string;
  136: 
  137:     /* This flag indicates that events were put into kbd_queue
  138:        while Emacs was running for some other KBOARD.
  139:        The flag means that, when Emacs goes into the any-kboard state again,
  140:        it should check this KBOARD to see if there is a complete command
  141:        waiting.
  142: 
  143:        Note that the kbd_queue field can be non-nil even when
  144:        kbd_queue_has_data is 0.  When we push back an incomplete
  145:        command, then this flag is 0, meaning we don't want to try
  146:        reading from this KBOARD again until more input arrives.  */
  147:     char kbd_queue_has_data;
  148: 
  149:     /* Nonzero means echo each character as typed.  */
  150:     char immediate_echo;
  151: 
  152:     /* If we have echoed a prompt string specified by the user,
  153:        this is its length in characters.  Otherwise this is -1.  */
  154:     char echo_after_prompt;
  155:   };
  156: 
  157: #ifdef MULTI_KBOARD
  158: /* Temporarily used before a frame has been opened, and for termcap frames */
  159: extern KBOARD *initial_kboard;
  160: 
  161: /* In the single-kboard state, this is the kboard
  162:    from which input is accepted.
  163: 
  164:    In the any-kboard state, this is the kboard from which we are
  165:    right now considering input.  We can consider input from another
  166:    kboard, but doing so requires throwing to wrong_kboard_jmpbuf.  */
  167: extern KBOARD *current_kboard;
  168: 
  169: /* A list of all kboard objects, linked through next_kboard.  */
  170: extern KBOARD *all_kboards;
  171: 
  172: /* Nonzero in the single-kboard state, 0 in the any-kboard state.  */
  173: extern int single_kboard;
  174: #else
  175: extern KBOARD the_only_kboard;
  176: #define current_kboard (&the_only_kboard)
  177: #define all_kboards (&the_only_kboard)
  178: #define single_kboard 1
  179: #endif
  180: ^L
  181: extern Lisp_Object Vlucid_menu_bar_dirty_flag;
  182: extern Lisp_Object Qrecompute_lucid_menubar, Qactivate_menubar_hook;
  183: 
  184: /* Total number of times read_char has returned.  */
  185: extern int num_input_events;
  186: 
  187: /* Total number of times read_char has returned, outside of macros.  */
  188: extern EMACS_INT num_nonmacro_input_events;
  189: 
  190: /* Nonzero means polling for input is temporarily suppressed.  */
  191: extern int poll_suppress_count;
  192: 
  193: /* Keymap mapping ASCII function key sequences onto their preferred forms.
  194:    Initialized by the terminal-specific lisp files.  */
  195: extern Lisp_Object Vfunction_key_map;
  196: 
  197: /* Vector holding the key sequence that invoked the current command.
  198:    It is reused for each command, and it may be longer than the current
  199:    sequence; this_command_key_count indicates how many elements
  200:    actually mean something.  */
  201: extern Lisp_Object this_command_keys;
  202: extern int this_command_key_count;
  203: 
  204: /* The frame in which the last input event occurred, or Qmacro if the
  205:    last event came from a macro.  We use this to determine when to
  206:    generate switch-frame events.  This may be cleared by functions
  207:    like Fselect_frame, to make sure that a switch-frame event is
  208:    generated by the next character.  */
  209: extern Lisp_Object internal_last_event_frame;
  210: ^L
  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: ^L
  241: /* Macros for dealing with lispy events.  */
  242: 
  243: /* True iff EVENT has data fields describing it (i.e. a mouse click).  */
  244: #define EVENT_HAS_PARAMETERS(event) (CONSP (event))
  245: 
  246: /* Extract the head from an event.
  247:    This works on composite and simple events.  */
  248: #define EVENT_HEAD(event) \
  249:   (EVENT_HAS_PARAMETERS (event) ? XCAR (event) : (event))
  250: 
  251: /* Extract the starting and ending positions from a composite event.  */
  252: #define EVENT_START(event) (XCAR (XCDR (event)))
  253: #define EVENT_END(event) (XCAR (XCDR (XCDR (event))))
  254: 
  255: /* Extract the click count from a multi-click event.  */
  256: #define EVENT_CLICK_COUNT(event) (Fnth (make_number (2), (event)))
  257: 
  258: /* Extract the fields of a position.  */
  259: #define POSN_WINDOW(posn) (XCAR (posn))
  260: #define POSN_POSN(posn) (XCAR (XCDR (posn)))
  261: #define POSN_SET_POSN(posn,x) (XSETCAR (XCDR (posn), (x)))
  262: #define POSN_WINDOW_POSN(posn) (XCAR (XCDR (XCDR (posn))))
  263: #define POSN_TIMESTAMP(posn) (XCAR (XCDR (XCDR (XCDR (posn)))))
  264: #define POSN_SCROLLBAR_PART(posn)       (Fnth (make_number (4), (posn)))
  265: 
  266: /* A cons (STRING . STRING-CHARPOS), or nil in mouse-click events.
  267:    It's a cons if the click is over a string in the mode line.  */
  268: 
  269: #define POSN_STRING(posn) (Fnth (make_number (4), (posn)))
  270: 
  271: /* If POSN_STRING is nil, event refers to buffer location.  */
  272: 
  273: #define POSN_INBUFFER_P(posn) (NILP (POSN_STRING (posn)))
  274: #define POSN_BUFFER_POSN(posn) (Fnth (make_number (5), (posn)))
  275: 
  276: /* Some of the event heads.  */
  277: extern Lisp_Object Qswitch_frame;
  278: 
  279: /* Properties on event heads.  */
  280: extern Lisp_Object Qevent_kind, Qevent_symbol_elements;
  281: 
  282: /* Getting an unmodified version of an event head.  */
  283: #define EVENT_HEAD_UNMODIFIED(event_head) \
  284:   (Fcar (Fget ((event_head), Qevent_symbol_elements)))
  285: 
  286: /* The values of Qevent_kind properties.  */
  287: extern Lisp_Object Qfunction_key, Qmouse_click, Qmouse_movement;
  288: extern Lisp_Object Qscroll_bar_movement;
  289: 
  290: /* Getting the kind of an event head.  */
  291: #define EVENT_HEAD_KIND(event_head) \
  292:   (Fget ((event_head), Qevent_kind))
  293: 
  294: /* Symbols to use for non-text mouse positions.  */
  295: extern Lisp_Object Qmode_line, Qvertical_line, Qheader_line;
  296: 
  297: /* Forward declaration for prototypes.  */
  298: struct input_event;
  299: 
  300: extern Lisp_Object parse_modifiers P_ ((Lisp_Object));
  301: extern Lisp_Object reorder_modifiers P_ ((Lisp_Object));
  302: extern Lisp_Object read_char P_ ((int, int, Lisp_Object *, Lisp_Object,
  303:                                   int *, EMACS_TIME *));
  304: /* User-supplied string to translate input characters through.  */
  305: extern Lisp_Object Vkeyboard_translate_table;
  306: 
  307: extern int parse_menu_item P_ ((Lisp_Object, int, int));
  308: 
  309: extern void echo_now P_ ((void));
  310: extern void init_kboard P_ ((KBOARD *));
  311: extern void delete_kboard P_ ((KBOARD *));
  312: extern void single_kboard_state P_ ((void));
  313: extern void not_single_kboard_state P_ ((KBOARD *));
  314: extern void push_frame_kboard P_ ((struct frame *));
  315: extern void pop_frame_kboard P_ ((void));
  316: extern void record_asynch_buffer_change P_ ((void));
  317: extern SIGTYPE input_poll_signal P_ ((int));
  318: extern void start_polling P_ ((void));
  319: extern void stop_polling P_ ((void));
  320: extern void set_poll_suppress_count P_ ((int));
  321: extern void gobble_input P_ ((int));
  322: extern int input_polling_used P_ ((void));
  323: extern void clear_input_pending P_ ((void));
  324: extern int requeued_events_pending_p P_ ((void));
  325: extern void bind_polling_period P_ ((int));
  326: extern void stuff_buffered_input P_ ((Lisp_Object));
  327: extern void clear_waiting_for_input P_ ((void));
  328: extern void swallow_events P_ ((int));
  329: extern int help_char_p P_ ((Lisp_Object));
  330: extern void quit_throw_to_read_char P_ ((void)) NO_RETURN;
  331: extern void cmd_error_internal P_ ((Lisp_Object, char *));
  332: extern int lucid_event_type_list_p P_ ((Lisp_Object));
  333: extern void kbd_buffer_store_event P_ ((struct input_event *));
  334: extern void kbd_buffer_store_event_hold P_ ((struct input_event *,
  335:                                              struct input_event *));
  336: extern void kbd_buffer_unget_event P_ ((struct input_event *));
  337: #ifdef POLL_FOR_INPUT
  338: extern void poll_for_input_1 P_ ((void));
  339: #endif
  340: extern void show_help_echo P_ ((Lisp_Object, Lisp_Object, Lisp_Object,
  341:                                 Lisp_Object, int));
  342: extern void gen_help_event P_ ((Lisp_Object, Lisp_Object, Lisp_Object,
  343:                                Lisp_Object, int));
  344: extern void kbd_buffer_store_help_event P_ ((Lisp_Object, Lisp_Object));
  345: extern Lisp_Object menu_item_eval_property P_ ((Lisp_Object));
  346: extern int  kbd_buffer_events_waiting P_ ((int));
  347: extern void add_user_signals P_ ((int, const char *));
  348: 
  349: /* arch-tag: 769cbade-1ba9-4950-b886-db265b061aa3
  350:    (do not change this comment) */