Update FSF's address in the preamble.
[bpt/emacs.git] / src / termhooks.h
CommitLineData
80856e74
JB
1/* Hooks by which low level terminal operations
2 can be made to call other routines.
3a22ee35 3 Copyright (C) 1985, 1986, 1993, 1994 Free Software Foundation, Inc.
80856e74
JB
4
5This file is part of GNU Emacs.
6
7GNU Emacs is free software; you can redistribute it and/or modify
8it under the terms of the GNU General Public License as published by
ffd56f97 9the Free Software Foundation; either version 2, or (at your option)
80856e74
JB
10any later version.
11
12GNU Emacs is distributed in the hope that it will be useful,
13but WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15GNU General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with GNU Emacs; see the file COPYING. If not, write to
3b7ad313
EN
19the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20Boston, MA 02111-1307, USA. */
80856e74 21
ec3f896c
JB
22\f
23/* Miscellanea. */
24
25/* If nonzero, send all terminal output characters to this stream also. */
26extern FILE *termscript;
27
28\f
29/* Text display hooks. */
80856e74
JB
30
31extern int (*cursor_to_hook) ();
32extern int (*raw_cursor_to_hook) ();
33
34extern int (*clear_to_end_hook) ();
0137dbf7 35extern int (*clear_frame_hook) ();
80856e74
JB
36extern int (*clear_end_of_line_hook) ();
37
38extern int (*ins_del_lines_hook) ();
39
40extern int (*change_line_highlight_hook) ();
41extern int (*reassert_line_highlight_hook) ();
42
43extern int (*insert_glyphs_hook) ();
44extern int (*write_glyphs_hook) ();
45extern int (*delete_glyphs_hook) ();
46
47extern int (*ring_bell_hook) ();
48
49extern int (*reset_terminal_modes_hook) ();
50extern int (*set_terminal_modes_hook) ();
51extern int (*update_begin_hook) ();
52extern int (*update_end_hook) ();
53extern int (*set_terminal_window_hook) ();
54
ec3f896c
JB
55
56\f
57/* Multi-frame and mouse support hooks. */
80856e74 58
a3c87d4e
JB
59enum scroll_bar_part {
60 scroll_bar_above_handle,
61 scroll_bar_handle,
62 scroll_bar_below_handle
20a558dc
JB
63};
64
65/* Return the current position of the mouse.
ec3f896c
JB
66
67 Set *f to the frame the mouse is in, or zero if the mouse is in no
68 Emacs frame. If it is set to zero, all the other arguments are
69 garbage.
70
a3c87d4e
JB
71 If the motion started in a scroll bar, set *bar_window to the
72 scroll bar's window, *part to the part the mouse is currently over,
73 *x to the position of the mouse along the scroll bar, and *y to the
74 overall length of the scroll bar.
ec3f896c
JB
75
76 Otherwise, set *bar_window to Qnil, and *x and *y to the column and
77 row of the character cell the mouse is over.
78
79 Set *time to the time the mouse was at the returned position.
80
81 This should clear mouse_moved until the next motion
82 event arrives. */
0137dbf7 83extern void (*mouse_position_hook) ( /* FRAME_PTR *f,
ec3f896c 84 Lisp_Object *bar_window,
a3c87d4e 85 enum scroll_bar_part *part,
265a9e55
JB
86 Lisp_Object *x,
87 Lisp_Object *y,
e5d77022 88 unsigned long *time */ );
265a9e55
JB
89
90/* The window system handling code should set this if the mouse has
91 moved since the last call to the mouse_position_hook. Calling that
92 hook should clear this. */
93extern int mouse_moved;
80856e74 94
0137dbf7 95/* When a frame's focus redirection is changed, this hook tells the
0f79a4ae 96 window system code to re-decide where to put the highlight. Under
265a9e55 97 X, this means that Emacs lies about where the focus is. */
0137dbf7 98extern void (*frame_rehighlight_hook) ( /* void */ );
62c07cc7 99
dbc4e1c1
JB
100/* If we're displaying frames using a window system that can stack
101 frames on top of each other, this hook allows you to bring a frame
102 to the front, or bury it behind all the other windows. If this
103 hook is zero, that means the device we're displaying on doesn't
104 support overlapping frames, so there's no need to raise or lower
105 anything.
106
107 If RAISE is non-zero, F is brought to the front, before all other
108 windows. If RAISE is zero, F is sent to the back, behind all other
109 windows. */
110extern void (*frame_raise_lower_hook) ( /* FRAME_PTR f, int raise */ );
ec3f896c
JB
111
112\f
a3c87d4e 113/* Scroll bar hooks. */
ec3f896c 114
a3c87d4e 115/* The representation of scroll bars is determined by the code which
ec3f896c
JB
116 implements them, except for one thing: they must be represented by
117 lisp objects. This allows us to place references to them in
118 Lisp_Windows without worrying about those references becoming
a3c87d4e 119 dangling references when the scroll bar is destroyed.
ec3f896c
JB
120
121 The window-system-independent portion of Emacs just refers to
a3c87d4e 122 scroll bars via their windows, and never looks inside the scroll bar
ec3f896c 123 representation; it always uses hook functions to do all the
a3c87d4e 124 scroll bar manipulation it needs.
ec3f896c 125
a3c87d4e
JB
126 The `vertical_scroll_bar' field of a Lisp_Window refers to that
127 window's scroll bar, or is nil if the window doesn't have a
128 scroll bar.
ec3f896c 129
a3c87d4e
JB
130 The `scroll_bars' and `condemned_scroll_bars' fields of a Lisp_Frame
131 are free for use by the scroll bar implementation in any way it sees
ec3f896c
JB
132 fit. They are marked by the garbage collector. */
133
134
a3c87d4e 135/* Set the vertical scroll bar for WINDOW to have its upper left corner
ec3f896c
JB
136 at (TOP, LEFT), and be LENGTH rows high. Set its handle to
137 indicate that we are displaying PORTION characters out of a total
138 of WHOLE characters, starting at POSITION. If WINDOW doesn't yet
a3c87d4e
JB
139 have a scroll bar, create one for it. */
140extern void (*set_vertical_scroll_bar_hook)
ec3f896c
JB
141 ( /* struct window *window,
142 int portion, int whole, int position */ );
20a558dc
JB
143
144
145/* The following three hooks are used when we're doing a thorough
a3c87d4e 146 redisplay of the frame. We don't explicitly know which scroll bars
20a558dc
JB
147 are going to be deleted, because keeping track of when windows go
148 away is a real pain - can you say set-window-configuration?
149 Instead, we just assert at the beginning of redisplay that *all*
a3c87d4e 150 scroll bars are to be removed, and then save scroll bars from the
b72e4ca8 151 fiery pit when we actually redisplay their window. */
20a558dc 152
a3c87d4e
JB
153/* Arrange for all scroll bars on FRAME to be removed at the next call
154 to `*judge_scroll_bars_hook'. A scroll bar may be spared if
155 `*redeem_scroll_bar_hook' is applied to its window before the judgement.
ec3f896c
JB
156
157 This should be applied to each frame each time its window tree is
a3c87d4e
JB
158 redisplayed, even if it is not displaying scroll bars at the moment;
159 if the HAS_SCROLL_BARS flag has just been turned off, only calling
160 this and the judge_scroll_bars_hook will get rid of them.
20a558dc 161
ec3f896c 162 If non-zero, this hook should be safe to apply to any frame,
a3c87d4e 163 whether or not it can support scroll bars, and whether or not it is
ec3f896c 164 currently displaying them. */
a3c87d4e 165extern void (*condemn_scroll_bars_hook)( /* FRAME_PTR *frame */ );
ec3f896c 166
a3c87d4e
JB
167/* Unmark WINDOW's scroll bar for deletion in this judgement cycle.
168 Note that it's okay to redeem a scroll bar that is not condemned. */
169extern void (*redeem_scroll_bar_hook)( /* struct window *window */ );
20a558dc 170
a3c87d4e
JB
171/* Remove all scroll bars on FRAME that haven't been saved since the
172 last call to `*condemn_scroll_bars_hook'.
ec3f896c
JB
173
174 This should be applied to each frame after each time its window
a3c87d4e
JB
175 tree is redisplayed, even if it is not displaying scroll bars at the
176 moment; if the HAS_SCROLL_BARS flag has just been turned off, only
177 calling this and condemn_scroll_bars_hook will get rid of them.
20a558dc 178
ec3f896c 179 If non-zero, this hook should be safe to apply to any frame,
a3c87d4e 180 whether or not it can support scroll bars, and whether or not it is
ec3f896c 181 currently displaying them. */
a3c87d4e 182extern void (*judge_scroll_bars_hook)( /* FRAME_PTR *FRAME */ );
20a558dc 183
ec3f896c
JB
184\f
185/* Input queue declarations and hooks. */
20a558dc 186
0dee3c4d 187/* Called to read input events. */
ec3f896c 188extern int (*read_socket_hook) ();
80856e74 189
0dee3c4d
RS
190/* Called when a frame's display becomes entirely up to date. */
191extern int (*frame_up_to_date_hook) ();
192
80856e74 193/* Expedient hack: only provide the below definitions to files that
026b8c1e 194 are prepared to handle lispy things. CONSP is defined iff lisp.h
265a9e55 195 has been included before this file. */
23c6349c 196#ifdef CONSP
80856e74 197
351c638e
RS
198enum event_kind
199{
200 no_event, /* nothing happened. This should never
80856e74 201 actually appear in the event queue. */
f05ddc05
JB
202
203 ascii_keystroke, /* The ASCII code is in .code, perhaps
204 with modifiers applied.
205 .modifiers holds the state of the
206 modifier keys.
ec3f896c
JB
207 .frame_or_window is the frame in
208 which the key was typed.
265a9e55
JB
209 .timestamp gives a timestamp (in
210 milliseconds) for the keystroke. */
351c638e 211 non_ascii_keystroke, /* .code is a number identifying the
80856e74
JB
212 function key. A code N represents
213 a key whose name is
214 function_key_names[N]; function_key_names
215 is a table in keyboard.c to which you
216 should feel free to add missing keys.
217 .modifiers holds the state of the
62c07cc7 218 modifier keys.
ec3f896c
JB
219 .frame_or_window is the frame in
220 which the key was typed.
265a9e55
JB
221 .timestamp gives a timestamp (in
222 milliseconds) for the keystroke. */
351c638e 223 mouse_click, /* The button number is in .code; it must
a1867fb1
JB
224 be >= 0 and < NUM_MOUSE_BUTTONS, defined
225 below.
80856e74
JB
226 .modifiers holds the state of the
227 modifier keys.
228 .x and .y give the mouse position,
1113d9db 229 in characters, within the window.
ec3f896c
JB
230 .frame_or_window gives the frame
231 the mouse click occurred in.
80856e74
JB
232 .timestamp gives a timestamp (in
233 milliseconds) for the click. */
351c638e 234 scroll_bar_click, /* .code gives the number of the mouse button
20a558dc
JB
235 that was clicked.
236 .modifiers holds the state of the modifier
237 keys.
80856e74 238 .part is a lisp symbol indicating which
a3c87d4e 239 part of the scroll bar got clicked.
20a558dc
JB
240 .x gives the distance from the start of the
241 scroll bar of the click; .y gives the total
242 length of the scroll bar.
ec3f896c 243 .frame_or_window gives the window
a3c87d4e 244 whose scroll bar was clicked in.
80856e74
JB
245 .timestamp gives a timestamp (in
246 milliseconds) for the click. */
351c638e
RS
247 selection_request_event, /* Another X client wants a selection from us.
248 See `struct selection_event'. */
3a6b074b 249 selection_clear_event, /* Another X client cleared our selection. */
026b8c1e 250 buffer_switch_event, /* A process filter has switched buffers. */
765a05bc 251 delete_window_event, /* An X client said "delete this window". */
f2afbef6 252 menu_bar_event, /* An event generated by the menu bar.
b90afe71 253 The frame_or_window field's cdr holds the
765a05bc
RS
254 Lisp-level event value.
255 (Only the toolkit version uses these.) */
f2afbef6 256 iconify_event, /* An X client iconified this window. */
c8b5ebed
RS
257 deiconify_event, /* An X client deiconified this window. */
258 menu_bar_activate_event /* A button press in the menu bar
259 (toolkit version only). */
351c638e
RS
260};
261
262/* If a struct input_event has a kind which is selection_request_event
263 or selection_clear_event, then its contents are really described
264 by `struct selection_event'; see xterm.h. */
265
266/* The keyboard input buffer is an array of these structures. Each one
267 represents some sort of input event - a keystroke, a mouse click, or
268 a window system event. These get turned into their lispy forms when
269 they are removed from the event queue. */
270
271struct input_event {
272
273 /* What kind of event was this? */
274 enum event_kind kind;
80856e74 275
653dfe64
RS
276 /* For an ascii_keystroke, this is the character.
277 For a non_ascii_keystroke, this is the keysym code.
9257d374 278 For a mouse event, this is the button number. */
653dfe64 279 int code;
a3c87d4e 280 enum scroll_bar_part part;
ec3f896c 281
46cfcdb4
RS
282 int modifiers; /* See enum below for interpretation. */
283
284 Lisp_Object x, y;
285 unsigned long timestamp;
286
ec3f896c
JB
287 /* This field is copied into a vector while the event is in the queue,
288 so that garbage collections won't kill it. */
b90afe71
KH
289 /* In a menu_bar_event, this is a cons cell whose car is the frame
290 and whose cdr is the Lisp object that is the event's value. */
46cfcdb4
RS
291 /* This field is last so that struct selection_input_event
292 does not overlap with it. */
ec3f896c 293 Lisp_Object frame_or_window;
80856e74 294};
351c638e 295\f
a1867fb1
JB
296/* This is used in keyboard.c, to tell how many buttons we will need
297 to track the positions of. */
298#define NUM_MOUSE_BUTTONS (5)
299
21cec071
JB
300/* Bits in the modifiers member of the input_event structure.
301 Note that reorder_modifiers assumes that the bits are in canonical
a1867fb1
JB
302 order.
303
304 The modifiers applied to mouse clicks are rather ornate. The
305 window-system-specific code should store mouse clicks with
45288343
JB
306 up_modifier or down_modifier set. Having an explicit down modifier
307 simplifies some of window-system-independent code; without it, the
308 code would have to recognize down events by checking if the event
309 is a mouse click lacking the click and drag modifiers.
310
311 The window-system independent code turns all up_modifier events
fbcd35bd
JB
312 bits into drag_modifier, click_modifier, double_modifier, or
313 triple_modifier events. The click_modifier has no written
314 representation in the names of the symbols used as event heads,
315 but it does appear in the Qevent_symbol_components property of the
316 event heads. */
80856e74 317enum {
a1867fb1
JB
318 up_modifier = 1, /* Only used on mouse buttons - always
319 turned into a click or a drag modifier
320 before lisp code sees the event. */
d82222e1
JB
321 down_modifier = 2, /* Only used on mouse buttons. */
322 drag_modifier = 4, /* This is never used in the event
a1867fb1
JB
323 queue; it's only used internally by
324 the window-system-independent code. */
d82222e1 325 click_modifier= 8, /* See drag_modifier. */
fbcd35bd
JB
326 double_modifier= 16, /* See drag_modifier. */
327 triple_modifier= 32, /* See drag_modifier. */
d82222e1
JB
328
329 /* The next four modifier bits are used also in keyboard events at
330 the Lisp level.
331
332 It's probably not the greatest idea to use the 2^23 bit for any
333 modifier. It may or may not be the sign bit, depending on
334 VALBITS, so using it to represent a modifier key means that
335 characters thus modified have different integer equivalents
336 depending on the architecture they're running on. Oh, and
337 applying XINT to a character whose 2^23 bit is set sign-extends
338 it, so you get a bunch of bits in the mask you didn't want.
339
340 The CHAR_ macros are defined in lisp.h. */
341 alt_modifier = CHAR_ALT, /* Under X, the XK_Alt_[LR] keysyms. */
342 super_modifier= CHAR_SUPER, /* Under X, the XK_Super_[LR] keysyms. */
343 hyper_modifier= CHAR_HYPER, /* Under X, the XK_Hyper_[LR] keysyms. */
344 shift_modifier= CHAR_SHIFT,
345 ctrl_modifier = CHAR_CTL,
6cd195e2 346 meta_modifier = CHAR_META /* Under X, the XK_Meta_[LR] keysyms. */
80856e74
JB
347};
348
80856e74 349#endif