src/termhooks.h

   1 /* Parameters and display hooks for output devices
   2    Copyright (C) 1985,86,93,94,2003  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 2, or (at your option)
   9 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; see the file COPYING.  If not, write to
  18 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19 Boston, MA 02111-1307, USA.  */
  20
  21 \f
  22 /* Miscellanea.   */
  23
  24 struct glyph;
  25 struct frame;
  26
  27 /* Only use prototypes when lisp.h has been included.  */
  28 #ifndef P_
  29 #define P_(X) ()
  30 #endif
  31 \f
  32
  33 enum scroll_bar_part {
  34   scroll_bar_above_handle,
  35   scroll_bar_handle,
  36   scroll_bar_below_handle,
  37   scroll_bar_up_arrow,
  38   scroll_bar_down_arrow,
  39   scroll_bar_to_top,
  40   scroll_bar_to_bottom,
  41   scroll_bar_end_scroll,
  42   scroll_bar_move_ratio
  43 };
  44
  45 \f
  46 /* Input queue declarations and hooks.  */
  47
  48 /* Expedient hack: only provide the below definitions to files that
  49    are prepared to handle lispy things.  CONSP is defined iff lisp.h
  50    has been included before this file.  */
  51 #ifdef CONSP
  52
  53 enum event_kind
  54 {
  55   NO_EVENT,                     /* nothing happened.  This should never
  56                                    actually appear in the event queue.  */
  57
  58   ASCII_KEYSTROKE_EVENT,        /* The ASCII code is in .code, perhaps
  59                                    with modifiers applied.
  60                                    .modifiers holds the state of the
  61                                    modifier keys.
  62                                    .frame_or_window is the frame in
  63                                    which the key was typed.
  64                                    .timestamp gives a timestamp (in
  65                                    milliseconds) for the keystroke.  */
  66   MULTIBYTE_CHAR_KEYSTROKE_EVENT,       /* The multibyte char code is in .code,
  67                                    perhaps with modifiers applied.
  68                                    The others are the same as
  69                                    ASCII_KEYSTROKE_EVENT.  */
  70   NON_ASCII_KEYSTROKE_EVENT,    /* .code is a number identifying the
  71                                    function key.  A code N represents
  72                                    a key whose name is
  73                                    function_key_names[N]; function_key_names
  74                                    is a table in keyboard.c to which you
  75                                    should feel free to add missing keys.
  76                                    .modifiers holds the state of the
  77                                    modifier keys.
  78                                    .frame_or_window is the frame in
  79                                    which the key was typed.
  80                                    .timestamp gives a timestamp (in
  81                                    milliseconds) for the keystroke.  */
  82   TIMER_EVENT,                  /* A timer fired.  */
  83   MOUSE_CLICK_EVENT,            /* The button number is in .code; it must
  84                                    be >= 0 and < NUM_MOUSE_BUTTONS, defined
  85                                    below.
  86                                    .modifiers holds the state of the
  87                                    modifier keys.
  88                                    .x and .y give the mouse position,
  89                                    in characters, within the window.
  90                                    .frame_or_window gives the frame
  91                                    the mouse click occurred in.
  92                                    .timestamp gives a timestamp (in
  93                                    milliseconds) for the click.  */
  94   WHEEL_EVENT,                  /* A wheel event is generated by a
  95                                    wheel on a mouse (e.g., MS
  96                                    Intellimouse).
  97                                    .modifiers holds the rotate
  98                                    direction (up or down), and the
  99                                    state of the modifier keys.
 100                                    .x and .y give the mouse position,
 101                                    in characters, within the window.
 102                                    .frame_or_window gives the frame
 103                                    the wheel event occurred in.
 104                                    .timestamp gives a timestamp (in
 105                                    milliseconds) for the event.  */
 106 #ifdef WINDOWSNT
 107   LANGUAGE_CHANGE_EVENT,        /* A LANGUAGE_CHANGE_EVENT is generated
 108                                    on WINDOWSNT when the keyboard layout
 109                                    or input language is changed by the
 110                                    user.  */
 111 #endif
 112   SCROLL_BAR_CLICK_EVENT,       /* .code gives the number of the mouse button
 113                                    that was clicked.
 114                                    .modifiers holds the state of the modifier
 115                                    keys.
 116                                    .part is a lisp symbol indicating which
 117                                    part of the scroll bar got clicked.
 118                                    .x gives the distance from the start of the
 119                                    scroll bar of the click; .y gives the total
 120                                    length of the scroll bar.
 121                                    .frame_or_window gives the window
 122                                    whose scroll bar was clicked in.
 123                                    .timestamp gives a timestamp (in
 124                                    milliseconds) for the click.  */
 125 #ifdef WINDOWSNT
 126   W32_SCROLL_BAR_CLICK_EVENT,   /* as for SCROLL_BAR_CLICK, but only generated
 127                                    by MS-Windows scroll bar controls. */
 128 #endif
 129   SELECTION_REQUEST_EVENT,      /* Another X client wants a selection from us.
 130                                    See `struct selection_event'.  */
 131   SELECTION_CLEAR_EVENT,        /* Another X client cleared our selection.  */
 132   BUFFER_SWITCH_EVENT,          /* A process filter has switched buffers.  */
 133   DELETE_WINDOW_EVENT,          /* An X client said "delete this window".  */
 134   MENU_BAR_EVENT,               /* An event generated by the menu bar.
 135                                    The frame_or_window field's cdr holds the
 136                                    Lisp-level event value.
 137                                    (Only the toolkit version uses these.)  */
 138   ICONIFY_EVENT,                /* An X client iconified this window.  */
 139   DEICONIFY_EVENT,              /* An X client deiconified this window.  */
 140   MENU_BAR_ACTIVATE_EVENT,      /* A button press in the menu bar
 141                                    (toolkit version only).  */
 142   DRAG_N_DROP_EVENT,            /* A drag-n-drop event is generated when
 143                                    files selected outside of Emacs are dropped
 144                                    onto an Emacs window.
 145                                    Currently used only on Windows NT.
 146                                    .modifiers holds the state of the
 147                                    modifier keys.
 148                                    .x and .y give the mouse position,
 149                                    in characters, within the window.
 150                                    .frame_or_window is a cons of the frame
 151                                    in which the drop was made and a list of
 152                                    the filenames of the dropped files.
 153                                    .timestamp gives a timestamp (in
 154                                    milliseconds) for the click.  */
 155   USER_SIGNAL_EVENT,            /* A user signal.
 156                                    code is a number identifying it,
 157                                    index into lispy_user_signals.  */
 158
 159   /* Help events.  Member `frame_or_window' of the input_event is the
 160      frame on which the event occurred, and member `arg' contains
 161      the help to show.  */
 162   HELP_EVENT,
 163
 164   /* An event from a tool-bar.  Member `arg' of the input event
 165      contains the tool-bar item selected.  If `frame_or_window'
 166      and `arg' are equal, this is a prefix event.  */
 167   TOOL_BAR_EVENT,
 168
 169   /* Queued from XTread_socket on FocusIn events.  Translated into
 170      `switch-frame' events in kbd_buffer_get_event, if necessary.  */
 171   FOCUS_IN_EVENT,
 172
 173   /* Generated when mouse moves over window not currently selected.  */
 174   SELECT_WINDOW_EVENT,
 175
 176   /* Queued from XTread_socket when session manager sends
 177      save yourself before shutdown. */
 178   SAVE_SESSION_EVENT
 179 };
 180
 181 /* If a struct input_event has a kind which is SELECTION_REQUEST_EVENT
 182    or SELECTION_CLEAR_EVENT, then its contents are really described
 183    by `struct selection_event'; see xterm.h.  */
 184
 185 /* The keyboard input buffer is an array of these structures.  Each one
 186    represents some sort of input event - a keystroke, a mouse click, or
 187    a window system event.  These get turned into their lispy forms when
 188    they are removed from the event queue.  */
 189
 190 struct input_event
 191 {
 192   /* What kind of event was this?  */
 193   enum event_kind kind;
 194
 195   /* For an ASCII_KEYSTROKE_EVENT and MULTIBYTE_CHAR_KEYSTROKE_EVENT,
 196      this is the character.
 197      For a NON_ASCII_KEYSTROKE_EVENT, this is the keysym code.
 198      For a mouse event, this is the button number.  */
 199   /* In WindowsNT, for a mouse wheel event, this is the delta.  */
 200   int code;
 201   enum scroll_bar_part part;
 202
 203   int modifiers;                /* See enum below for interpretation.  */
 204
 205   Lisp_Object x, y;
 206   unsigned long timestamp;
 207
 208   /* This is padding just to put the frame_or_window field
 209      past the size of struct selection_event.  */
 210   int *padding[2];
 211
 212   /* This field is copied into a vector while the event is in the queue,
 213      so that garbage collections won't kill it.  */
 214   /* In a menu_bar_event, this is a cons cell whose car is the frame
 215      and whose cdr is the Lisp object that is the event's value.  */
 216   /* This field is last so that struct selection_input_event
 217      does not overlap with it.  */
 218   Lisp_Object frame_or_window;
 219
 220   /* Additional event argument.  This is used for TOOL_BAR_EVENTs and
 221      HELP_EVENTs and avoids calling Fcons during signal handling.  */
 222   Lisp_Object arg;
 223 };
 224
 225 #define EVENT_INIT(event) bzero (&(event), sizeof (struct input_event))
 226
 227 /* Bits in the modifiers member of the input_event structure.
 228    Note that reorder_modifiers assumes that the bits are in canonical
 229    order.
 230
 231    The modifiers applied to mouse clicks are rather ornate.  The
 232    window-system-specific code should store mouse clicks with
 233    up_modifier or down_modifier set.  Having an explicit down modifier
 234    simplifies some of window-system-independent code; without it, the
 235    code would have to recognize down events by checking if the event
 236    is a mouse click lacking the click and drag modifiers.
 237
 238    The window-system independent code turns all up_modifier events
 239    bits into drag_modifier, click_modifier, double_modifier, or
 240    triple_modifier events.  The click_modifier has no written
 241    representation in the names of the symbols used as event heads,
 242    but it does appear in the Qevent_symbol_components property of the
 243    event heads.  */
 244 enum {
 245   up_modifier   =   1,          /* Only used on mouse buttons - always
 246                                    turned into a click or a drag modifier
 247                                    before lisp code sees the event.  */
 248   down_modifier =   2,          /* Only used on mouse buttons.  */
 249   drag_modifier =   4,          /* This is never used in the event
 250                                    queue; it's only used internally by
 251                                    the window-system-independent code.  */
 252   click_modifier=   8,          /* See drag_modifier.  */
 253   double_modifier= 16,          /* See drag_modifier.  */
 254   triple_modifier= 32,          /* See drag_modifier.  */
 255
 256   /* The next four modifier bits are used also in keyboard events at
 257      the Lisp level.
 258
 259      It's probably not the greatest idea to use the 2^23 bit for any
 260      modifier.  It may or may not be the sign bit, depending on
 261      VALBITS, so using it to represent a modifier key means that
 262      characters thus modified have different integer equivalents
 263      depending on the architecture they're running on.  Oh, and
 264      applying XINT to a character whose 2^23 bit is set sign-extends
 265      it, so you get a bunch of bits in the mask you didn't want.
 266
 267      The CHAR_ macros are defined in lisp.h.  */
 268   alt_modifier  =  CHAR_ALT,    /* Under X, the XK_Alt_[LR] keysyms.  */
 269   super_modifier=  CHAR_SUPER,  /* Under X, the XK_Super_[LR] keysyms.  */
 270   hyper_modifier=  CHAR_HYPER,  /* Under X, the XK_Hyper_[LR] keysyms.  */
 271   shift_modifier=  CHAR_SHIFT,
 272   ctrl_modifier =  CHAR_CTL,
 273   meta_modifier =  CHAR_META    /* Under X, the XK_Meta_[LR] keysyms.  */
 274 };
 275
 276 #endif /* CONSP */
 277
 278 \f
 279 /* Display-local parameters. */
 280 struct display
 281 {
 282   /* Chain of all displays. */
 283   struct display *next_display;
 284
 285   /* The number of frames that are on this display. */
 286   int reference_count;
 287
 288   /* The type of the display. */
 289   enum output_method type;
 290
 291   /* Display-type dependent data shared amongst all frames on this display. */
 292   union display_info
 293   {
 294     struct tty_display_info *tty;     /* termchar.h */
 295     struct x_display_info *x;         /* xterm.h */
 296   } display_info;
 297
 298 \f
 299   /* Terminal characteristics. */
 300   /* XXX Are these really used on non-termcap displays? */
 301
 302   int must_write_spaces;        /* Nonzero means spaces in the text must
 303                                    actually be output; can't just skip over
 304                                    some columns to leave them blank.  */
 305   int fast_clear_end_of_line;   /* Nonzero means terminal has a `ce' string */
 306
 307   int line_ins_del_ok;          /* Terminal can insert and delete lines */
 308   int char_ins_del_ok;          /* Terminal can insert and delete chars */
 309   int scroll_region_ok;         /* Terminal supports setting the scroll
 310                                    window */
 311   int scroll_region_cost;       /* Cost of setting the scroll window,
 312                                    measured in characters. */
 313   int memory_below_frame;       /* Terminal remembers lines scrolled
 314                                    off bottom */
 315
 316 #if 0  /* These are not used anywhere. */
 317   /* EMACS_INT baud_rate; */    /* Output speed in baud */
 318   int min_padding_speed;        /* Speed below which no padding necessary. */
 319   int dont_calculate_costs;     /* Nonzero means don't bother computing
 320                                    various cost tables; we won't use them. */
 321 #endif
 322
 323 \f
 324   /* Window-based redisplay interface for this device (0 for tty
 325      devices). */
 326   struct redisplay_interface *rif;
 327
 328   /* Frame-based redisplay interface. */
 329
 330   /* Text display hooks.  */
 331
 332   void (*cursor_to_hook) P_ ((int vpos, int hpos));
 333   void (*raw_cursor_to_hook) P_ ((int, int));
 334
 335   void (*clear_to_end_hook) P_ ((void));
 336   void (*clear_frame_hook) P_ ((void));
 337   void (*clear_end_of_line_hook) P_ ((int));
 338
 339   void (*ins_del_lines_hook) P_ ((int, int));
 340
 341   void (*insert_glyphs_hook) P_ ((struct glyph *s, int n));
 342   void (*write_glyphs_hook) P_ ((struct glyph *s, int n));
 343   void (*delete_glyphs_hook) P_ ((int));
 344
 345   void (*ring_bell_hook) P_ ((void));
 346
 347   void (*reset_terminal_modes_hook) P_ ((struct display *));
 348   void (*set_terminal_modes_hook) P_ ((struct display *));
 349   void (*update_begin_hook) P_ ((struct frame *));
 350   void (*update_end_hook) P_ ((struct frame *));
 351   void (*set_terminal_window_hook) P_ ((int));
 352
 353   /* Multi-frame and mouse support hooks.  */
 354
 355   /* Return the current position of the mouse.
 356
 357      Set *f to the frame the mouse is in, or zero if the mouse is in no
 358      Emacs frame.  If it is set to zero, all the other arguments are
 359      garbage.
 360
 361      If the motion started in a scroll bar, set *bar_window to the
 362      scroll bar's window, *part to the part the mouse is currently over,
 363      *x to the position of the mouse along the scroll bar, and *y to the
 364      overall length of the scroll bar.
 365
 366      Otherwise, set *bar_window to Qnil, and *x and *y to the column and
 367      row of the character cell the mouse is over.
 368
 369      Set *time to the time the mouse was at the returned position.
 370
 371      This should clear mouse_moved until the next motion
 372      event arrives.  */
 373   void (*mouse_position_hook) P_ ((struct frame **f, int,
 374                                    Lisp_Object *bar_window,
 375                                    enum scroll_bar_part *part,
 376                                    Lisp_Object *x,
 377                                    Lisp_Object *y,
 378                                    unsigned long *time));
 379
 380   /* The window system handling code should set this if the mouse has
 381      moved since the last call to the mouse_position_hook.  Calling that
 382      hook should clear this.  */
 383   int mouse_moved;
 384
 385   /* When a frame's focus redirection is changed, this hook tells the
 386      window system code to re-decide where to put the highlight.  Under
 387      X, this means that Emacs lies about where the focus is.  */
 388   void (*frame_rehighlight_hook) P_ ((struct frame *));
 389
 390   /* If we're displaying frames using a window system that can stack
 391      frames on top of each other, this hook allows you to bring a frame
 392      to the front, or bury it behind all the other windows.  If this
 393      hook is zero, that means the device we're displaying on doesn't
 394      support overlapping frames, so there's no need to raise or lower
 395      anything.
 396
 397      If RAISE is non-zero, F is brought to the front, before all other
 398      windows.  If RAISE is zero, F is sent to the back, behind all other
 399      windows.  */
 400   void (*frame_raise_lower_hook) P_ ((struct frame *f, int raise));
 401
 402   \f
 403   /* Scroll bar hooks.  */
 404
 405   /* The representation of scroll bars is determined by the code which
 406      implements them, except for one thing: they must be represented by
 407      lisp objects.  This allows us to place references to them in
 408      Lisp_Windows without worrying about those references becoming
 409      dangling references when the scroll bar is destroyed.
 410
 411      The window-system-independent portion of Emacs just refers to
 412      scroll bars via their windows, and never looks inside the scroll bar
 413      representation; it always uses hook functions to do all the
 414      scroll bar manipulation it needs.
 415
 416      The `vertical_scroll_bar' field of a Lisp_Window refers to that
 417      window's scroll bar, or is nil if the window doesn't have a
 418      scroll bar.
 419
 420      The `scroll_bars' and `condemned_scroll_bars' fields of a Lisp_Frame
 421      are free for use by the scroll bar implementation in any way it sees
 422      fit.  They are marked by the garbage collector.  */
 423
 424
 425   /* Set the vertical scroll bar for WINDOW to have its upper left corner
 426      at (TOP, LEFT), and be LENGTH rows high.  Set its handle to
 427      indicate that we are displaying PORTION characters out of a total
 428      of WHOLE characters, starting at POSITION.  If WINDOW doesn't yet
 429      have a scroll bar, create one for it.  */
 430   void (*set_vertical_scroll_bar_hook) P_ ((struct window *window,
 431                                             int portion, int whole,
 432                                             int position));
 433
 434
 435   /* The following three hooks are used when we're doing a thorough
 436      redisplay of the frame.  We don't explicitly know which scroll bars
 437      are going to be deleted, because keeping track of when windows go
 438      away is a real pain - can you say set-window-configuration?
 439      Instead, we just assert at the beginning of redisplay that *all*
 440      scroll bars are to be removed, and then save scroll bars from the
 441      fiery pit when we actually redisplay their window.  */
 442
 443   /* Arrange for all scroll bars on FRAME to be removed at the next call
 444      to `*judge_scroll_bars_hook'.  A scroll bar may be spared if
 445      `*redeem_scroll_bar_hook' is applied to its window before the judgement.
 446
 447      This should be applied to each frame each time its window tree is
 448      redisplayed, even if it is not displaying scroll bars at the moment;
 449      if the HAS_SCROLL_BARS flag has just been turned off, only calling
 450      this and the judge_scroll_bars_hook will get rid of them.
 451
 452      If non-zero, this hook should be safe to apply to any frame,
 453      whether or not it can support scroll bars, and whether or not it is
 454      currently displaying them.  */
 455   void (*condemn_scroll_bars_hook) P_ ((struct frame *frame));
 456
 457   /* Unmark WINDOW's scroll bar for deletion in this judgement cycle.
 458      Note that it's okay to redeem a scroll bar that is not condemned.  */
 459   void (*redeem_scroll_bar_hook) P_ ((struct window *window));
 460
 461   /* Remove all scroll bars on FRAME that haven't been saved since the
 462      last call to `*condemn_scroll_bars_hook'.
 463
 464      This should be applied to each frame after each time its window
 465      tree is redisplayed, even if it is not displaying scroll bars at the
 466      moment; if the HAS_SCROLL_BARS flag has just been turned off, only
 467      calling this and condemn_scroll_bars_hook will get rid of them.
 468
 469      If non-zero, this hook should be safe to apply to any frame,
 470      whether or not it can support scroll bars, and whether or not it is
 471      currently displaying them.  */
 472   void (*judge_scroll_bars_hook) P_ ((struct frame *FRAME));
 473
 474 \f
 475   /* Called to read input events.  */
 476   int (*read_socket_hook) P_ ((struct display *, struct input_event *, int, int));
 477
 478   /* Called when a frame's display becomes entirely up to date.  */
 479   void (*frame_up_to_date_hook) P_ ((struct frame *));
 480
 481 \f
 482   /* Called to delete the device-specific portions of a frame that is
 483      on this display. */
 484   void (*delete_frame_hook) P_ ((struct frame *));
 485
 486   /* Called after the last frame on this display is deleted.
 487      If this is NULL, then the generic delete_frame() is called.
 488
 489      Fdelete_frame ensures that there are no live frames on the
 490      display when it calls this hook. */
 491   void (*delete_display_hook) P_ ((struct display *));
 492
 493 };
 494
 495
 496 /* Chain of all displays currently in use. */
 497 extern struct display *display_list;
 498
 499 #define FRAME_MUST_WRITE_SPACES(f) ((f)->display->must_write_spaces)
 500 #define FRAME_FAST_CLEAR_END_OF_LINE(f) ((f)->display->fast_clear_end_of_line)
 501 #define FRAME_LINE_INS_DEL_OK(f) ((f)->display->line_ins_del_ok)
 502 #define FRAME_CHAR_INS_DEL_OK(f) ((f)->display->char_ins_del_ok)
 503 #define FRAME_SCROLL_REGION_OK(f) ((f)->display->scroll_region_ok)
 504 #define FRAME_SCROLL_REGION_COST(f) ((f)->display->scroll_region_cost)
 505 #define FRAME_MEMORY_BELOW_FRAME(f) ((f)->display->memory_below_frame)
 506
 507 #define FRAME_RIF(f) ((f)->display->rif)
 508
 509 #define FRAME_DISPLAY(f) ((f)->display)
 510
 511 /* FRAME_WINDOW_P tests whether the frame is a window, and is
 512    defined to be the predicate for the window system being used.  */
 513
 514 #ifdef HAVE_X_WINDOWS
 515 #define FRAME_WINDOW_P(f) FRAME_X_P (f)
 516 #endif
 517 #ifdef HAVE_NTGUI
 518 #define FRAME_WINDOW_P(f) FRAME_W32_P (f)
 519 #endif
 520 #ifdef MAC_OS
 521 #define FRAME_WINDOW_P(f) FRAME_MAC_P (f)
 522 #endif
 523 #ifndef FRAME_WINDOW_P
 524 #define FRAME_WINDOW_P(f) (0)
 525 #endif
 526
 527
 528 extern struct display *create_display P_ ((void));
 529 extern void delete_display P_ ((struct display *));
 530
 531 /* The initial display device, created by initial_term_init. */
 532 extern struct display *initial_display;
 533
 534 /* arch-tag: 33a00ecc-52b5-4186-a410-8801ac9f087d
 535    (do not change this comment) */